{
  "openapi": "3.2.0",
  "info": {
    "title": "AxeTip Financial & Card Routing API",
    "version": "1.0.0",
    "description": "REST API for credit card pricing terms, CFPB card agreement filings, ISO 18245 Merchant Category Codes, merchant routing, and Federal Reserve benchmark rates.",
    "contact": {
      "name": "AxeTip Developer Operations",
      "email": "api@axetip.com",
      "url": "https://www.axetip.com/api/"
    },
    "license": {
      "name": "AxeTip Developer Terms & Data Standards",
      "url": "https://www.axetip.com/legal/terms/"
    }
  },
  "servers": [
    {
      "url": "https://www.axetip.com",
      "description": "Production API"
    }
  ],
  "paths": {
    "/api/cards": {
      "get": {
        "summary": "Query Credit Card Pricing and Comparisons",
        "description": "Retrieve comprehensive product terms, fee structures, rewards matrices, and live Federal Reserve H.15 effective APR calculations for 1 to 5 cards.",
        "operationId": "getCards",
        "parameters": [
          {
            "name": "cards",
            "in": "query",
            "required": true,
            "description": "Comma-separated list of card identifiers, common aliases, or search queries (e.g. 'amex-gold,chase-sapphire-preferred' or 'csp,gold'). Up to 5 cards supported.",
            "schema": {
              "type": "string",
              "example": "amex-gold,chase-sapphire-preferred"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful retrieval of card datasets and live benchmark calculations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters or exceeded comparison limit (maximum 5 cards).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "No cards found matching the requested identifier(s).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (standard community limit: 60 requests per minute).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Cards"
        ]
      },
      "post": {
        "summary": "Batch Query Credit Cards",
        "description": "Accepts an array of card identifiers or queries in a JSON request body.",
        "operationId": "postCards",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "cards"
                ],
                "properties": {
                  "cards": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Array of 1 to 5 card slugs or query strings.",
                    "example": [
                      "capitalone-venture-x",
                      "chase-sapphire-reserve"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful card data retrieval.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Cards"
        ]
      }
    },
    "/api/mcc": {
      "get": {
        "summary": "Query ISO 18245 Merchant Category Codes",
        "description": "Retrieve standardized ISO 18245 technical definitions, payment network classifications, reward category mappings, and optimal card yield rankings.",
        "operationId": "getMcc",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": false,
            "description": "4-digit ISO 18245 Merchant Category Code (e.g. 5812, 5411, 7011). Multiple codes can be comma-separated.",
            "schema": {
              "type": "string",
              "example": "5812"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter all MCCs belonging to a specific reward category (e.g. dining, supermarkets, travel, airline, hotel, gas).",
            "schema": {
              "type": "string",
              "example": "dining"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful MCC retrieval.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MccResponse"
                }
              }
            }
          },
          "404": {
            "description": "MCC code not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "MCC"
        ]
      },
      "post": {
        "summary": "Batch Query ISO 18245 MCCs",
        "description": "Accepts an array of 4-digit MCC codes or a category filter in a JSON request body.",
        "operationId": "postMcc",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "codes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "5812",
                      "5411"
                    ]
                  },
                  "category": {
                    "type": "string",
                    "example": "dining"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful batch MCC retrieval.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MccResponse"
                }
              }
            }
          }
        },
        "tags": [
          "MCC"
        ]
      }
    },
    "/api/merchant": {
      "get": {
        "summary": "Query Merchant Entities and MCC Logic",
        "description": "Resolve commercial merchants, brand aliases, primary and alternative MCC codes, stock tickers, issuer-specific nuances, and optimal card reward pairings.",
        "operationId": "getMerchant",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Fuzzy search query or merchant alias (e.g. \"doordash\", \"caviar\", \"lyft\", \"costco\"). Supports comma-separated multi-queries.",
            "schema": {
              "type": "string",
              "example": "doordash"
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Exact merchant slug identifier (e.g. \"doordash\", \"costco\", \"uber\").",
            "schema": {
              "type": "string",
              "example": "costco"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful merchant data retrieval.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MerchantResponse"
                }
              }
            }
          },
          "404": {
            "description": "Merchant not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Merchant"
        ]
      },
      "post": {
        "summary": "Batch Query Merchants",
        "description": "Query multiple merchant entities by slugs or aliases in a JSON request body.",
        "operationId": "postMerchant",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "merchants": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "doordash",
                      "lyft",
                      "costco"
                    ]
                  },
                  "id": {
                    "type": "string",
                    "example": "costco"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful batch merchant retrieval.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MerchantResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Merchant"
        ]
      }
    },
    "/api/benchmark": {
      "get": {
        "summary": "Federal Reserve Macroeconomic Benchmark & Rate Cycle Engine",
        "description": "Exposes live Wall Street Journal / Federal Reserve Prime Rate (H.15), Secured Overnight Financing Rate (SOFR), Effective Fed Funds Rate (EFFR), FOMC meeting calendar, Net Interest Margin (NIM) credit spreads, and the 10-year historical cycle time-series.",
        "operationId": "getBenchmark",
        "parameters": [
          {
            "name": "series",
            "in": "query",
            "required": false,
            "description": "Optional series selector ('history' returns chronological historical adjustments).",
            "schema": {
              "type": "string",
              "enum": [
                "history",
                "overview"
              ],
              "example": "history"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum historical records to return (1 to 100, default 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "example": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current Federal Reserve benchmarks and rate cycle analytics.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BenchmarkResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Benchmark"
        ]
      }
    },
    "/api/optimize": {
      "get": {
        "summary": "Point-of-Sale Transaction Card Optimizer",
        "description": "Determines the mathematically optimal credit card to use for a specific merchant transaction or MCC, evaluating held cards, co-brand bonuses, and payment network acceptance quirks (e.g. Costco POS).",
        "operationId": "getOptimize",
        "parameters": [
          {
            "name": "merchant",
            "in": "query",
            "required": false,
            "description": "Merchant name, alias, or slug (e.g. 'doordash', 'costco', 'delta').",
            "schema": {
              "type": "string",
              "example": "doordash"
            }
          },
          {
            "name": "mcc",
            "in": "query",
            "required": false,
            "description": "Optional 4-digit MCC override.",
            "schema": {
              "type": "string",
              "example": "5812"
            }
          },
          {
            "name": "amount",
            "in": "query",
            "required": false,
            "description": "Transaction amount in USD (default 100.00).",
            "schema": {
              "type": "number",
              "example": 45
            }
          },
          {
            "name": "held_cards",
            "in": "query",
            "required": false,
            "description": "Comma-separated list of held card IDs (e.g. 'amex-gold,chase-sapphire-preferred,capitalone-venture-x').",
            "schema": {
              "type": "string",
              "example": "amex-gold,chase-sapphire-preferred,capitalone-venture-x"
            }
          },
          {
            "name": "point_valuation_cents",
            "in": "query",
            "required": false,
            "description": "Point/mile valuation in cents (default 1.0).",
            "schema": {
              "type": "number",
              "example": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Optimized card recommendation and ranking across held portfolio.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OptimizeTransactionResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Optimize"
        ]
      },
      "post": {
        "summary": "Batch Transaction & Monthly Spend Basket Optimizer",
        "description": "Accepts a point-of-sale transaction or a multi-category monthly expenditure basket. Computes the optimal card routing across held cards, checks network quirks, and identifies the single best unheld card yielding the highest marginal annual alpha.",
        "operationId": "postOptimize",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/OptimizeTransactionRequest"
                  },
                  {
                    "$ref": "#/components/schemas/OptimizeBasketRequest"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Optimization result with portfolio routing and marginal alpha card.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/OptimizeTransactionResponse"
                    },
                    {
                      "$ref": "#/components/schemas/OptimizeBasketResponse"
                    }
                  ]
                }
              }
            }
          }
        },
        "tags": [
          "Optimize"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "CardResponse": {
        "type": "object",
        "required": [
          "source",
          "benchmark",
          "status",
          "mode",
          "cards_count",
          "cards"
        ],
        "properties": {
          "source": {
            "type": "string",
            "example": "AxeTip 2026 Tier 1 Data"
          },
          "benchmark": {
            "$ref": "#/components/schemas/MacroeconomicBenchmark"
          },
          "disclaimer": {
            "type": "string",
            "example": "Informational only; terms subject to issuer change. Not financial advice. Governed by https://www.axetip.com/legal/terms/"
          },
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ],
            "example": "success"
          },
          "mode": {
            "type": "string",
            "enum": [
              "lookup",
              "comparison"
            ],
            "example": "comparison"
          },
          "cards_count": {
            "type": "integer",
            "example": 2
          },
          "ambiguity_notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Explanatory notes when a query matches multiple variants."
          },
          "unmatched_queries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of input queries that yielded no matching card records."
          },
          "verdict": {
            "type": "string",
            "description": "Deterministic comparison analysis or executive card summary.",
            "example": "Amex Gold carries a $325.00 annual fee with 4x dining and groceries, while Chase Sapphire Preferred features a $95.00 annual fee with 3x dining and a 10% anniversary point boost."
          },
          "cards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CardDetail"
            }
          }
        }
      },
      "MacroeconomicBenchmark": {
        "type": "object",
        "required": [
          "prime_rate",
          "as_of",
          "source"
        ],
        "properties": {
          "prime_rate": {
            "$ref": "#/components/schemas/InterestRate"
          },
          "as_of": {
            "type": "string",
            "format": "date",
            "example": "2026-09-16"
          },
          "next_fomc_meeting": {
            "type": "string",
            "format": "date",
            "example": "2026-10-28"
          },
          "source": {
            "type": "string",
            "example": "Federal Reserve Board of Governors H.15"
          }
        }
      },
      "CardDetail": {
        "type": "object",
        "required": [
          "id",
          "name",
          "issuer",
          "network",
          "annual_fee",
          "pricing",
          "rewards",
          "calculated"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "amex-gold"
          },
          "name": {
            "type": "string",
            "example": "American Express® Gold Card"
          },
          "issuer": {
            "type": "string",
            "example": "American Express"
          },
          "network": {
            "type": "string",
            "example": "American Express"
          },
          "canonical_url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical product comparison and specification URL on AxeTip.",
            "example": "https://www.axetip.com/card/amex-gold/"
          },
          "media": {
            "$ref": "#/components/schemas/CardMedia"
          },
          "issuer_upgrades": {
            "type": "array",
            "description": "Contractual benefit upgrades negotiated by the issuer that exceed the standard requirements of the payment network tier.",
            "items": {
              "$ref": "#/components/schemas/IssuerUpgrade"
            }
          },
          "network_alpha": {
            "type": "array",
            "deprecated": true,
            "description": "Deprecated alias for issuer_upgrades. Benefit upgrades exceeding network standard.",
            "items": {
              "$ref": "#/components/schemas/IssuerUpgrade"
            }
          },
          "annual_fee": {
            "$ref": "#/components/schemas/MoneyAmount"
          },
          "is_premium": {
            "type": "boolean",
            "example": true
          },
          "pricing": {
            "$ref": "#/components/schemas/PricingStructure"
          },
          "rewards": {
            "$ref": "#/components/schemas/RewardsStructure"
          },
          "calculated": {
            "$ref": "#/components/schemas/CalculatedMetrics"
          },
          "insurance_protections": {
            "type": "object",
            "additionalProperties": true
          },
          "application_rules": {
            "type": "object",
            "additionalProperties": true
          },
          "eligibility": {
            "type": "object",
            "properties": {
              "min_fico_score": {
                "type": "integer",
                "example": 670
              },
              "fico_type": {
                "type": "string",
                "example": "FICO 8"
              },
              "recommended_range": {
                "type": "string",
                "example": "Good to Excellent"
              }
            }
          }
        }
      },
      "PricingStructure": {
        "type": "object",
        "required": [
          "annual_fee",
          "apr_margins",
          "grace_period"
        ],
        "properties": {
          "annual_fee": {
            "$ref": "#/components/schemas/MoneyAmount"
          },
          "apr_margins": {
            "type": "object",
            "properties": {
              "min": {
                "type": "number",
                "example": 12.74
              },
              "max": {
                "type": "number",
                "example": 21.74
              }
            }
          },
          "cash_advance_margin": {
            "type": "number",
            "example": 21.99
          },
          "penalty_margin": {
            "type": "number",
            "nullable": true,
            "example": 26.74
          },
          "grace_period": {
            "type": "integer",
            "description": "Grace period in days to avoid finance charges.",
            "example": 25
          },
          "foreign_transaction_fee": {
            "type": "object",
            "properties": {
              "percentage": {
                "type": "number",
                "example": 0
              },
              "is_allowed": {
                "type": "boolean",
                "example": true
              }
            }
          },
          "late_fee": {
            "type": "number",
            "example": 40
          },
          "offsets": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "example": "Dining Statement Credit"
                },
                "value": {
                  "type": "number",
                  "example": 120
                },
                "restriction": {
                  "type": "string",
                  "example": "Up to $10/month"
                }
              }
            }
          }
        }
      },
      "RewardsStructure": {
        "type": "object",
        "properties": {
          "base": {
            "type": "object",
            "properties": {
              "rate": {
                "type": "number",
                "example": 1
              },
              "currency": {
                "type": "string",
                "example": "amex_points"
              }
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "example": "Restaurants Worldwide"
                },
                "rate": {
                  "type": "number",
                  "example": 4
                },
                "currency": {
                  "type": "string",
                  "example": "amex_points"
                },
                "limit": {
                  "type": "number",
                  "nullable": true,
                  "example": 50000
                }
              }
            }
          }
        }
      },
      "CalculatedMetrics": {
        "type": "object",
        "required": [
          "effective_purchase_apr"
        ],
        "properties": {
          "effective_purchase_apr": {
            "type": "object",
            "properties": {
              "margin_min": {
                "$ref": "#/components/schemas/InterestRate"
              },
              "margin_max": {
                "$ref": "#/components/schemas/InterestRate"
              },
              "effective_min": {
                "$ref": "#/components/schemas/InterestRate"
              },
              "effective_max": {
                "$ref": "#/components/schemas/InterestRate"
              },
              "formula": {
                "type": "string",
                "example": "prime_rate (7.00%) + bank_margin"
              }
            }
          },
          "effective_cash_advance_apr": {
            "$ref": "#/components/schemas/InterestRate"
          }
        }
      },
      "CardMedia": {
        "type": "object",
        "description": "Standardized, edge-cached artwork and payment network vector assets.",
        "properties": {
          "card_art_url": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "High-resolution WebP card face artwork hosted on AxeTip CDN.",
            "example": "https://www.axetip.com/img/cards/amex-gold.webp"
          },
          "network_logo_url": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Payment network vector SVG conforming to ISO/IEC 7812.",
            "example": "https://www.axetip.com/img/network/american-express.svg"
          },
          "format": {
            "type": "string",
            "example": "webp"
          },
          "dimensions": {
            "type": "object",
            "properties": {
              "width": {
                "type": "integer",
                "example": 480
              },
              "height": {
                "type": "integer",
                "example": 304
              }
            }
          }
        }
      },
      "IssuerUpgrade": {
        "type": "object",
        "properties": {
          "benefit": {
            "type": "string",
            "example": "insurance_protections.auto_rental.type"
          },
          "feature_name": {
            "type": "string",
            "example": "Auto Rental Collision Damage Waiver"
          },
          "network_standard": {
            "type": "string",
            "example": "Secondary Coverage"
          },
          "network_baseline": {
            "type": "string",
            "description": "Deprecated alias for network_standard.",
            "example": "Secondary Coverage"
          },
          "card_feature": {
            "type": "string",
            "example": "Primary Coverage"
          },
          "market_advantage": {
            "type": "string",
            "example": "Primary rental waiver outperforming Visa Signature standard"
          }
        }
      },
      "NetworkAlphaUpgrade": {
        "type": "object",
        "deprecated": true,
        "description": "Deprecated alias for IssuerUpgrade schema.",
        "allOf": [
          {
            "$ref": "#/components/schemas/IssuerUpgrade"
          }
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "Could not find any cards matching the provided query."
          },
          "unmatched_queries": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "MccResponse": {
        "type": "object",
        "required": [
          "status",
          "meta"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "count": {
            "type": "integer",
            "example": 1
          },
          "data": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/MccRecord"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MccRecord"
                }
              }
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "governing_standard": {
                "type": "string",
                "example": "ISO 18245:2023"
              },
              "jurisdiction": {
                "type": "string",
                "example": "Global Payment Network Interchange Standards"
              },
              "sources": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "timestamp": {
                "type": "string",
                "example": "2026-11-13T20:00:00.000Z"
              }
            }
          }
        }
      },
      "MccRecord": {
        "type": "object",
        "required": [
          "code",
          "title",
          "reward_category",
          "is_cash_advance",
          "optimal_cards"
        ],
        "properties": {
          "code": {
            "type": "string",
            "example": "5812"
          },
          "title": {
            "type": "string",
            "example": "Eating Places And Restaurants"
          },
          "reward_category": {
            "type": "string",
            "example": "dining"
          },
          "is_cash_advance": {
            "type": "boolean",
            "example": false
          },
          "related_mccs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "merchants": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          },
          "optimal_cards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OptimalCard"
            }
          },
          "optimal_card": {
            "$ref": "#/components/schemas/OptimalCard"
          }
        }
      },
      "MerchantResponse": {
        "type": "object",
        "required": [
          "status",
          "meta"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "count": {
            "type": "integer",
            "example": 1
          },
          "data": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/MerchantRecord"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MerchantRecord"
                }
              }
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "taxonomy": {
                "type": "string",
                "example": "AxeTip Global Merchant Entity Index"
              },
              "total_merchants_indexed": {
                "type": "integer",
                "example": 2417
              },
              "timestamp": {
                "type": "string",
                "example": "2026-11-13T20:00:00.000Z"
              }
            }
          }
        }
      },
      "MerchantRecord": {
        "type": "object",
        "required": [
          "id",
          "name",
          "primary_mcc",
          "optimal_cards"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "doordash"
          },
          "name": {
            "type": "string",
            "example": "DoorDash"
          },
          "ticker": {
            "type": "string",
            "nullable": true,
            "example": "DASH"
          },
          "exchange": {
            "type": "string",
            "nullable": true,
            "example": "NASDAQ"
          },
          "industry": {
            "type": "string",
            "example": "Food Delivery / Logistics"
          },
          "category": {
            "type": "string",
            "example": "Dining"
          },
          "website": {
            "type": "string",
            "nullable": true,
            "example": "https://www.doordash.com"
          },
          "primary_mcc": {
            "type": "string",
            "example": "5812"
          },
          "primary_mcc_title": {
            "type": "string",
            "nullable": true,
            "example": "Eating Places And Restaurants"
          },
          "secondary_mccs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "mcc_logic": {
            "type": "object",
            "properties": {
              "primary_description": {
                "type": "string"
              },
              "issuer_quirks_and_notes": {
                "type": "string"
              }
            }
          },
          "optimal_cards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OptimalCard"
            }
          },
          "optimal_card": {
            "$ref": "#/components/schemas/OptimalCard"
          }
        }
      },
      "OptimalCard": {
        "type": "object",
        "description": "Optimal card pairing with structured yield and fee value objects.",
        "required": [
          "id",
          "name",
          "issuer",
          "annual_fee",
          "reward_yield",
          "canonical_url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "amex-gold"
          },
          "name": {
            "type": "string",
            "example": "American Express® Gold Card"
          },
          "issuer": {
            "type": "string",
            "example": "American Express"
          },
          "annual_fee": {
            "$ref": "#/components/schemas/MoneyAmount"
          },
          "reward_yield": {
            "$ref": "#/components/schemas/RewardYield"
          },
          "canonical_url": {
            "type": "string",
            "format": "uri",
            "example": "https://www.axetip.com/card/amex-gold/"
          },
          "partnership_note": {
            "type": "string",
            "nullable": true
          },
          "match_reason": {
            "type": "string",
            "example": "Co-brand partnership match"
          },
          "is_co_brand": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "MoneyAmount": {
        "type": "object",
        "description": "Structured monetary value object conforming to institutional financial standards (minor units + formatted text).",
        "required": [
          "value",
          "cents",
          "formatted",
          "currency"
        ],
        "properties": {
          "value": {
            "type": "number",
            "format": "float",
            "description": "Numeric amount in base currency units.",
            "example": 325
          },
          "cents": {
            "type": "integer",
            "description": "Exact integer value in minor currency units (cents) for zero-error accounting math.",
            "example": 32500
          },
          "formatted": {
            "type": "string",
            "description": "Fully formatted currency string with symbol and fixed decimal precision.",
            "example": "$325.00"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 three-letter currency code.",
            "example": "USD"
          }
        }
      },
      "InterestRate": {
        "type": "object",
        "description": "Structured interest rate object conforming to Wall Street basis points (bps) standards.",
        "required": [
          "value",
          "bps",
          "formatted"
        ],
        "properties": {
          "value": {
            "type": "number",
            "format": "float",
            "description": "Percentage rate.",
            "example": 7
          },
          "bps": {
            "type": "integer",
            "description": "Exact integer value in Basis Points (1 bp = 0.01% = 0.0001) for deterministic financial calculations.",
            "example": 700
          },
          "formatted": {
            "type": "string",
            "description": "Fixed-precision percentage string.",
            "example": "7.00%"
          }
        }
      },
      "RewardYield": {
        "type": "object",
        "description": "Structured reward multiplier or cashback yield object.",
        "required": [
          "value",
          "unit",
          "formatted",
          "basis_points"
        ],
        "properties": {
          "value": {
            "type": "number",
            "format": "float",
            "description": "Numeric multiplier or percentage.",
            "example": 4
          },
          "unit": {
            "type": "string",
            "description": "Yield measurement unit ('x' for points/miles multipliers, '%' for cash back).",
            "example": "x"
          },
          "formatted": {
            "type": "string",
            "description": "Display string.",
            "example": "4.0x"
          },
          "basis_points": {
            "type": "integer",
            "description": "Yield expressed in basis points (e.g. 4.0x/4% = 400 bps).",
            "example": 400
          }
        }
      },
      "BenchmarkResponse": {
        "type": "object",
        "required": [
          "status",
          "source",
          "as_of"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "source": {
            "type": "string",
            "example": "Federal Reserve Board of Governors H.15 & NY Fed"
          },
          "regulatory_jurisdiction": {
            "type": "string",
            "example": "United States Federal Reserve System"
          },
          "as_of": {
            "type": "string",
            "example": "2026-09-16"
          },
          "benchmarks": {
            "type": "object",
            "properties": {
              "prime_rate": {
                "$ref": "#/components/schemas/InterestRate"
              },
              "sofr": {
                "$ref": "#/components/schemas/InterestRate"
              },
              "effective_federal_funds_rate": {
                "$ref": "#/components/schemas/InterestRate"
              }
            }
          },
          "fomc_calendar": {
            "type": "object",
            "properties": {
              "last_decision_date": {
                "type": "string",
                "example": "2026-09-16"
              },
              "last_rate_change_bps": {
                "type": "integer",
                "example": 25
              },
              "next_fomc_meeting": {
                "type": "string",
                "example": "2026-10-28"
              }
            }
          },
          "credit_market_spreads": {
            "type": "object",
            "properties": {
              "national_average_purchase_apr": {
                "$ref": "#/components/schemas/InterestRate"
              },
              "net_interest_margin_spread": {
                "$ref": "#/components/schemas/InterestRate"
              }
            }
          },
          "historical_cycle": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "example": "2026-09-16"
                },
                "prime_rate": {
                  "$ref": "#/components/schemas/InterestRate"
                },
                "change": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "number",
                      "example": 0.25
                    },
                    "bps": {
                      "type": "integer",
                      "example": 25
                    },
                    "formatted": {
                      "type": "string",
                      "example": "+0.25%"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "OptimizeTransactionRequest": {
        "type": "object",
        "required": [
          "merchant"
        ],
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "transaction"
            ],
            "example": "transaction"
          },
          "merchant": {
            "type": "string",
            "example": "doordash"
          },
          "mcc": {
            "type": "string",
            "example": "5812"
          },
          "amount": {
            "$ref": "#/components/schemas/MoneyAmount"
          },
          "held_cards": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "amex-gold",
              "capitalone-venture-x"
            ]
          },
          "point_valuation_cents": {
            "type": "number",
            "example": 1
          }
        }
      },
      "OptimizeBasketRequest": {
        "type": "object",
        "required": [
          "spending"
        ],
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "basket"
            ],
            "example": "basket"
          },
          "held_cards": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "capitalone-venture-x",
              "chase-sapphire-preferred"
            ]
          },
          "spending": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "number",
                  "example": 800
                },
                "cents": {
                  "type": "integer",
                  "example": 80000
                }
              }
            }
          },
          "point_valuation_cents": {
            "type": "number",
            "example": 1
          }
        }
      },
      "OptimizeTransactionResponse": {
        "type": "object",
        "required": [
          "status",
          "mode",
          "transaction",
          "recommended_card"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "mode": {
            "type": "string",
            "example": "transaction"
          },
          "transaction": {
            "type": "object",
            "properties": {
              "merchant": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "id": {
                    "type": "string",
                    "example": "doordash"
                  },
                  "name": {
                    "type": "string",
                    "example": "DoorDash"
                  },
                  "primary_mcc": {
                    "type": "string",
                    "example": "5812"
                  },
                  "category": {
                    "type": "string",
                    "example": "dining"
                  }
                }
              },
              "mcc": {
                "type": "string",
                "example": "5812"
              },
              "category": {
                "type": "string",
                "example": "dining"
              },
              "amount": {
                "$ref": "#/components/schemas/MoneyAmount"
              }
            }
          },
          "recommended_card": {
            "type": "object",
            "properties": {
              "card_id": {
                "type": "string",
                "example": "amex-gold"
              },
              "card_name": {
                "type": "string",
                "example": "American Express® Gold Card"
              },
              "issuer": {
                "type": "string",
                "example": "American Express"
              },
              "reward_yield": {
                "$ref": "#/components/schemas/RewardYield"
              },
              "estimated_return": {
                "$ref": "#/components/schemas/MoneyAmount"
              },
              "match_reason": {
                "type": "string"
              },
              "canonical_url": {
                "type": "string"
              }
            }
          },
          "held_cards_ranking": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "rank": {
                  "type": "integer",
                  "example": 1
                },
                "card_id": {
                  "type": "string",
                  "example": "amex-gold"
                },
                "reward_yield": {
                  "$ref": "#/components/schemas/RewardYield"
                },
                "estimated_return": {
                  "$ref": "#/components/schemas/MoneyAmount"
                }
              }
            }
          },
          "marginal_alpha_card": {
            "type": "object",
            "nullable": true,
            "properties": {
              "card_id": {
                "type": "string",
                "example": "hilton-honors-aspire"
              },
              "card_name": {
                "type": "string",
                "example": "Hilton Honors American Express Aspire Card"
              },
              "reward_yield": {
                "$ref": "#/components/schemas/RewardYield"
              },
              "estimated_return": {
                "$ref": "#/components/schemas/MoneyAmount"
              },
              "canonical_url": {
                "type": "string"
              }
            }
          },
          "network_alerts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "severity": {
                  "type": "string",
                  "example": "warning"
                },
                "type": {
                  "type": "string",
                  "example": "pos_network_restriction"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "OptimizeBasketResponse": {
        "type": "object",
        "required": [
          "status",
          "mode",
          "portfolio_summary",
          "category_routing"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "mode": {
            "type": "string",
            "example": "basket"
          },
          "portfolio_summary": {
            "type": "object",
            "properties": {
              "total_monthly_spend": {
                "$ref": "#/components/schemas/MoneyAmount"
              },
              "total_annual_spend": {
                "$ref": "#/components/schemas/MoneyAmount"
              },
              "monthly_reward_return": {
                "$ref": "#/components/schemas/MoneyAmount"
              },
              "annual_reward_return": {
                "$ref": "#/components/schemas/MoneyAmount"
              },
              "held_cards_count": {
                "type": "integer",
                "example": 2
              }
            }
          },
          "category_routing": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "spend": {
                  "$ref": "#/components/schemas/MoneyAmount"
                },
                "routed_card": {
                  "type": "string",
                  "example": "Amex Gold"
                },
                "reward_yield": {
                  "$ref": "#/components/schemas/RewardYield"
                },
                "monthly_return": {
                  "$ref": "#/components/schemas/MoneyAmount"
                }
              }
            }
          },
          "marginal_alpha_card": {
            "type": "object",
            "nullable": true,
            "properties": {
              "card_id": {
                "type": "string",
                "example": "amex-hilton-surpass"
              },
              "card_name": {
                "type": "string",
                "example": "Hilton Honors American Express Surpass Card"
              },
              "annual_fee": {
                "$ref": "#/components/schemas/MoneyAmount"
              },
              "net_incremental_annual_alpha": {
                "$ref": "#/components/schemas/MoneyAmount"
              },
              "canonical_url": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "core-engines",
      "summary": "Cards & Merchant Routing",
      "description": "Card terms, ISO 18245 MCC taxonomy, and merchant alias resolution."
    },
    {
      "name": "Cards",
      "summary": "Credit Cards",
      "parent": "core-engines",
      "description": "Credit card terms, bank margin schedules, and APRs calculated from live Fed Prime."
    },
    {
      "name": "MCC",
      "summary": "Merchant Category Codes",
      "parent": "core-engines",
      "description": "ISO 18245 merchant category codes and reward classifications."
    },
    {
      "name": "Merchant",
      "summary": "Merchants",
      "parent": "core-engines",
      "description": "Merchant database, alias resolution, and co-brand reward yields."
    },
    {
      "name": "macro-intelligence",
      "summary": "Benchmarks & Optimization",
      "description": "Federal Reserve money market benchmarks, rate spreads, and card routing."
    },
    {
      "name": "Benchmark",
      "summary": "Benchmark Rates",
      "parent": "macro-intelligence",
      "description": "Federal Reserve H.15 money market rates, SOFR, EFFR, and rate spreads."
    },
    {
      "name": "Optimize",
      "summary": "Card Optimization",
      "parent": "macro-intelligence",
      "description": "Point-of-sale transaction routing and spend basket optimization."
    }
  ],
  "": "https://www.axetip.com/api/openapi-3.2.json"
}
