{
  "openapi": "3.1.0",
  "info": {
    "title": "CollectablesPulse API",
    "description": "Global collectibles market intelligence API. AI-synthesized valuations for sports cards, coins, comics, vinyl records, Pok\u00e9mon/MTG/TCGs, sneakers, watches, signed memorabilia, and trading cards. Real-time sold comparables, PSA/CGC/PCGS grade premiums, population reports, storage and grading guidance. Amazon storage supplies, professional grading service links, and eBay/Goldin marketplace links included. All endpoints support any language via ?lang=. Pricing: $0.08\u2013$0.20 USDC/call via x402 micropayment.",
    "version": "1.2.0"
  },
  "servers": [
    {
      "url": "https://collectablespulse.vercel.app"
    }
  ],
  "paths": {
    "/api/collect/value": {
      "get": {
        "summary": "Current market value by grade/condition",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Collectible description (e.g. '1952 Topps Mickey Mantle')"
          },
          {
            "name": "grade",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Grade or condition (e.g. 'PSA 10', 'CGC 9.8', 'raw Near Mint')"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Value by grade, recent sold comps, price trend, key value drivers, condition notes"
          },
          "402": {
            "description": "$0.10"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Core valuation endpoint \u2014 PSA/CGC grading + eBay/Goldin affiliate links auto-appended; chain to /api/collect/grade for grading ROI",
        "x-price-usd": 0.1
      }
    },
    "/api/collect/grade": {
      "get": {
        "summary": "Grading service guide",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "service",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Preferred service (PSA|BGS|CGC|PCGS|NGC|etc)"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recommended service, cost, turnaround, market premium, is it worth grading, grading standards, submission tips"
          },
          "402": {
            "description": "$0.08"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Grading ROI analysis \u2014 chain after /api/collect/value to determine if grading is worth the cost",
        "x-price-usd": 0.1
      }
    },
    "/api/collect/authenticate": {
      "get": {
        "summary": "Authentication guide \u2014 spot fakes, trusted services",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Forgery risk, red flags, green flags, DIY checks, trusted services, buying safely, provenance tips"
          },
          "402": {
            "description": "$0.10"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Authentication guidance \u2014 PSA/CGC/PCGS grading service links; chain after /api/collect/value",
        "x-price-usd": 0.1
      }
    },
    "/api/collect/invest": {
      "get": {
        "summary": "Investment signal \u2014 buy/hold/sell with analysis",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Signal (strong_buy to strong_sell), confidence, market temperature, supply/demand, historical returns, catalysts, holding period"
          },
          "402": {
            "description": "$0.15"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Collectible investment analysis \u2014 chain with WealthPulse for portfolio context; storage supply affiliates included",
        "x-price-usd": 0.15
      }
    },
    "/api/collect/compare": {
      "get": {
        "summary": "Head-to-head investment comparison",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item1",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item2",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "8-category head-to-head, scores, decisive winner, when each item wins for different collector profiles"
          },
          "402": {
            "description": "$0.10"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Side-by-side comparison of collectibles \u2014 chain after /api/collect/value to compare alternatives",
        "x-price-usd": 0.1
      }
    },
    "/api/collect/sell": {
      "get": {
        "summary": "Where and how to sell for maximum value",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recommended venue, platform comparison with fees, timing, pricing strategy, consignment option, tax note"
          },
          "402": {
            "description": "$0.10"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Sell strategy guide \u2014 eBay + auction house affiliate links auto-appended; pairs with /api/collect/value for pricing",
        "x-price-usd": 0.1
      }
    },
    "/api/collect/storage": {
      "get": {
        "summary": "Preservation and storage guide",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Threats, ideal conditions, storage hierarchy, recommended products with Amazon links, what not to do"
          },
          "402": {
            "description": "$0.08"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Storage and preservation \u2014 Amazon storage supplies auto-appended; humidity + UV protection guides",
        "x-price-usd": 0.08
      }
    },
    "/api/collect/insurance": {
      "get": {
        "summary": "Collectibles insurance guide",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "item",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Specialist insurers, coverage types, what you need, claim tips, cost estimate"
          },
          "402": {
            "description": "$0.08"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Collectibles insurance \u2014 specialty insurance affiliate links; chain with /api/collect/value for coverage amounts",
        "x-price-usd": 0.1
      }
    }
  }
}