{"openapi":"3.1.0","info":{"title":"decipher-ranker","description":"Merchant analytics and ranking for the x402 ecosystem. Get rank position, competitor benchmarks, pricing analysis, and improvement recommendations.","version":"1.0.0","x-guidance":"decipher-ranker helps API providers understand their marketplace position.\n\nFREE ENDPOINTS (no payment):\n- GET /categories — Browse all API categories with counts\n- GET /leaderboard — Top APIs by category\n- GET /preview — Quick merchant lookup by domain/URL (instant-win, no auth)\n- POST /report/origin — Full rank report for your origin (SIWX wallet identity required)\n\nPAID ENDPOINTS ($0.03 each):\n- POST /report/competitive — Deep competitive analysis with gap analysis\n- POST /report/merchant — Deep-dive on any merchant by address\n\nStart with GET /preview for a quick check, then use POST /report/origin (free, SIWX) for detailed tips, or the paid endpoints for competitive intelligence.","guidance":"decipher-ranker helps API providers understand their marketplace position.\n\nFREE ENDPOINTS (no payment):\n- GET /categories — Browse all API categories with counts\n- GET /leaderboard — Top APIs by category\n- GET /preview — Quick merchant lookup by domain/URL (instant-win, no auth)\n- POST /report/origin — Full rank report for your origin (SIWX wallet identity required)\n\nPAID ENDPOINTS ($0.03 each):\n- POST /report/competitive — Deep competitive analysis with gap analysis\n- POST /report/merchant — Deep-dive on any merchant by address\n\nStart with GET /preview for a quick check, then use POST /report/origin (free, SIWX) for detailed tips, or the paid endpoints for competitive intelligence.","contact":{"email":"zaryabafser2000@gmail.com"}},"servers":[{"url":"https://decipherranker.com"}],"tags":[{"name":"Categories"},{"name":"Leaderboard"},{"name":"Preview"},{"name":"Report"}],"paths":{"/api/report/competitive":{"post":{"operationId":"report_competitive","summary":"Get a detailed competitive analysis. Returns top 10 competitors in your category with gap analysis, pricing benchmarks, and recommendations.","tags":["Report"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string","format":"uri","description":"Your API origin URL"}},"required":["origin"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"message":{"type":"string"},"origin":{"type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"your_rank":{"anyOf":[{"type":"number"},{"type":"null"}]},"total_competitors":{"type":"number"},"competitors":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"gap_analysis":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"pricing_benchmark":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"recommendations":{"type":"array","items":{"type":"string"}},"ai_insights":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["found"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}}}},"/api/report/origin":{"post":{"operationId":"report_origin","summary":"Get a free basic ranking report for your API origin. Returns category, competitor count, price position, and improvement tips.","tags":["Report"],"security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string","format":"uri","description":"The origin URL of the merchant (e.g. https://mesh.heurist.xyz)"}},"required":["origin"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"origin":{"type":"string"},"message":{"type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"rank_position":{"anyOf":[{"type":"number"},{"type":"null"}]},"total_competitors":{"type":"number"},"price_position":{"type":"string"},"description_quality":{"type":"number"},"description_quality_breakdown":{"anyOf":[{"type":"object","properties":{"score":{"type":"number"},"lengthScore":{"type":"number"},"keywordDensity":{"type":"number"},"categoryKeywordPresence":{"type":"number"},"structuralSpecificity":{"type":"number"},"length":{"type":"number"},"fluffScore":{"type":"number"},"buzzwords":{"type":"array","items":{"type":"string"}},"verdict":{"type":"string"}},"required":["score","lengthScore","keywordDensity","categoryKeywordPresence","structuralSpecificity","length","fluffScore","buzzwords","verdict"],"additionalProperties":false},{"type":"null"}]},"tag_quality":{"anyOf":[{"type":"object","properties":{"score":{"type":"number"},"relevance":{"type":"number"},"specificity":{"type":"number"},"count_score":{"type":"number"},"spam":{"type":"boolean"},"count":{"type":"number"},"issues":{"type":"array","items":{"type":"string"}},"suggested_tags":{"type":"array","items":{"type":"string"}}},"required":["score","relevance","specificity","count_score","spam","count","issues","suggested_tags"],"additionalProperties":false},{"type":"null"}]},"listing_completeness":{"type":"number"},"tips":{"type":"array","items":{"type":"string"}},"last_updated":{"type":"string"},"discovery_layers":{"anyOf":[{"type":"object","properties":{"cdp_bazaar":{"type":"object","properties":{"indexed":{"type":"boolean"},"note":{"type":"string"}},"required":["indexed","note"],"additionalProperties":false},"x402scan":{"type":"object","properties":{"indexed":{"type":"boolean"},"note":{"type":"string"}},"required":["indexed","note"],"additionalProperties":false},"agent_cash":{"type":"object","properties":{"indexed":{"type":"boolean"},"note":{"type":"string"}},"required":["indexed","note"],"additionalProperties":false},"layer_alignment_score":{"type":"number"}},"required":["cdp_bazaar","x402scan","agent_cash","layer_alignment_score"],"additionalProperties":false},{"type":"null"}]},"supply_gap":{"anyOf":[{"type":"object","properties":{"category_name":{"type":"string"},"average_gap_ratio":{"type":"number"},"total_buried_merchants":{"type":"number"},"total_category_merchants":{"type":"number"},"refreshed_at":{"type":"string"},"merchant_is_buried":{"type":"boolean"},"per_query":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"cdp_results":{"type":"number"},"category_merchant_count":{"type":"number"},"buried_count":{"type":"number"},"gap_ratio":{"type":"number"}},"required":["query","cdp_results","category_merchant_count","buried_count","gap_ratio"],"additionalProperties":false}}},"required":["category_name","average_gap_ratio","total_buried_merchants","total_category_merchants","refreshed_at","merchant_is_buried","per_query"],"additionalProperties":false},{"type":"null"}]},"completeness_grade":{"anyOf":[{"type":"string","enum":["A","B","C","D","F"]},{"type":"null"}]},"action_roadmap":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"priority":{"type":"string","enum":["high","medium","low"]},"component":{"type":"string"},"issue":{"type":"string"},"expected_impact":{"type":"string"}},"required":["action","priority","component","issue","expected_impact"],"additionalProperties":false}},"chain_count":{"type":"number"},"weight_rationale":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"weight":{"type":"number"},"reason":{"type":"string"},"what_moves_it":{"type":"string"},"merchant_can_control":{"type":"boolean"}},"required":["weight","reason","what_moves_it","merchant_can_control"],"additionalProperties":false}},{"type":"null"}]},"rank_trend":{"anyOf":[{"type":"object","properties":{"trend_direction":{"type":"string","enum":["improving","declining","stable","insufficient_data"]},"score_change_30d":{"anyOf":[{"type":"number"},{"type":"null"}]},"rank_change_30d":{"anyOf":[{"type":"number"},{"type":"null"}]},"volume_change_30d":{"anyOf":[{"type":"number"},{"type":"null"}]},"buyer_change_30d":{"anyOf":[{"type":"number"},{"type":"null"}]},"snapshots_available":{"type":"number"},"first_snapshot_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_snapshot_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"interpretation":{"type":"string"}},"required":["trend_direction","score_change_30d","rank_change_30d","volume_change_30d","buyer_change_30d","snapshots_available","first_snapshot_date","last_snapshot_date","interpretation"],"additionalProperties":false},{"type":"null"}]}},"required":["found"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/report/merchant":{"post":{"operationId":"report_merchant","summary":"Get a detailed merchant deep-dive by wallet address. Returns volume stats, buyer diversity, trend signals, and recommendations.","tags":["Report"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.03"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","minLength":32,"maxLength":48,"description":"The payee address (EVM or Solana) of the merchant"},"chain":{"default":"base","description":"Blockchain network (mainnet only)","type":"string","enum":["base","solana","polygon"]}},"required":["address"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"message":{"type":"string"},"address":{"type":"string"},"chain":{"type":"string"},"service_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"rank":{"anyOf":[{"type":"number"},{"type":"null"}]},"all_time_stats_available":{"type":"boolean"},"volume":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"buyers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"pricing":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"trends":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"recommendations":{"type":"array","items":{"type":"string"}}},"required":["found"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}}}},"/api/categories":{"get":{"operationId":"categories","summary":"Browse all API categories in the x402 ecosystem with merchant counts, median pricing, and the top merchants per category.","tags":["Categories"],"security":[],"responses":{"200":{"description":"Successful response"}}}},"/api/leaderboard":{"get":{"operationId":"leaderboard","summary":"Top x402 merchants ranked by decipher score, optionally filtered to a single category.","tags":["Leaderboard"],"security":[],"parameters":[{"in":"query","name":"category","schema":{"description":"Filter to a single category by name; omit for all categories","type":"string"},"description":"Filter to a single category by name; omit for all categories"},{"in":"query","name":"limit","schema":{"default":50,"description":"Number of merchants to return (1-100)","type":"integer","minimum":1,"maximum":100},"description":"Number of merchants to return (1-100)"}],"responses":{"200":{"description":"Successful response"}}}},"/api/preview":{"get":{"operationId":"preview","summary":"Quick merchant lookup for the homepage instant-win feature. Returns rank, score, grade, and category — enough to show value, with upsell links to the full report endpoints.","tags":["Preview"],"security":[],"parameters":[{"in":"query","name":"origin","schema":{"type":"string","minLength":3,"maxLength":500,"description":"Domain or URL of the x402 merchant to look up"},"required":true,"description":"Domain or URL of the x402 merchant to look up"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"origin":{"type":"string"},"message":{"type":"string"},"merchant":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"score":{"type":"number"},"grade":{"type":"string"},"rank":{"anyOf":[{"type":"number"},{"type":"null"}]},"total_in_category":{"type":"number"},"resource_count":{"type":"number"},"chain":{"type":"string"}},"required":["name","category","score","grade","rank","total_in_category","resource_count","chain"],"additionalProperties":false},"teaser":{"type":"object","properties":{"has_tips":{"type":"boolean"},"tip_count":{"type":"number"},"available_reports":{"type":"array","items":{"type":"string"}}},"required":["has_tips","tip_count","available_reports"],"additionalProperties":false},"links":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["found","origin","links"],"additionalProperties":false}}}}}}}},"components":{"securitySchemes":{"siwx":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X"}}}}