{
  "openapi": "3.1.0",
  "info": {
    "title": "CryptoPulse API",
    "description": "Global cryptocurrency intelligence API. 10 endpoints: DeFi yield farming across Ethereum/Base/Arbitrum/Solana (DeFiLlama live TVL + APY), personalized strategy builder, crypto security framework (with Ledger/Trezor hardware wallet links), threat intelligence, exchange comparison (with Coinbase/Gemini/Kraken/Binance exchange affiliate links, experience-aware), crypto tax guidance for 20+ countries (with Koinly/CoinLedger tax software links), beginner onboarding (exchange links), spending guide, crypto-friendly banking, and merchant payment setup. Powered by CoinGecko, DeFiLlama, Fear & Greed Index, and Tavily. All require x402 micropayment (USDC on Base).",
    "version": "1.2.0",
    "contact": {
      "url": "https://cryptopulse.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://cryptopulse.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Send a GET request without this header to receive a 402 with payment requirements. Sign the payment and retry with the PAYMENT-SIGNATURE header.",
        "required": true
      }
    }
  },
  "security": [
    {
      "x402": []
    }
  ],
  "paths": {
    "/api/yield": {
      "get": {
        "summary": "DeFi yield intelligence",
        "description": "Real-time DeFi yield opportunities ranked by risk-adjusted return across protocols and chains. Includes Berachain PoL spotlight, protocol TVL data, and entry steps.",
        "operationId": "yield",
        "parameters": [
          {
            "name": "chain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "all"
            },
            "description": "Filter by chain: ethereum, base, arbitrum, berachain, solana, or all"
          },
          {
            "name": "risk",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "conservative",
                "moderate",
                "aggressive"
              ],
              "default": "moderate"
            },
            "description": "Risk profile filter"
          }
        ],
        "responses": {
          "200": {
            "description": "DeFi yield opportunities with rankings and entry steps"
          },
          "402": {
            "description": "Payment required. Respond with PAYMENT-SIGNATURE to proceed."
          }
        },
        "security": [
          {
            "x402": []
          }
        ],
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1,
        "x-agent-chaining": "Pair with /api/security to ensure self-custody setup before depositing into protocols"
      }
    },
    "/api/strategy": {
      "get": {
        "summary": "Personalized DeFi strategy builder",
        "description": "Custom DeFi allocation plan with step-by-step entry paths for your capital, risk tolerance, and goals. Agent-executable output.",
        "operationId": "strategy",
        "parameters": [
          {
            "name": "capital",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "default": 10000
            },
            "description": "Capital in USD"
          },
          {
            "name": "risk",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "conservative",
                "moderate",
                "aggressive"
              ],
              "default": "moderate"
            }
          },
          {
            "name": "chain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "all"
            }
          },
          {
            "name": "goal",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "yield",
                "growth",
                "stable",
                "privacy"
              ],
              "default": "yield"
            }
          },
          {
            "name": "timeframe",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 180
            },
            "description": "Investment timeframe in days"
          }
        ],
        "responses": {
          "200": {
            "description": "Personalized DeFi strategy with allocations and entry/exit paths"
          },
          "402": {
            "description": "Payment required."
          }
        },
        "security": [
          {
            "x402": []
          }
        ],
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.2,
        "x-agent-chaining": "Follow with /api/yield for specific DeFi pools matching the recommended strategy"
      }
    },
    "/api/security": {
      "get": {
        "summary": "Crypto security framework",
        "description": "Hardware wallet selection, seed phrase storage, multi-sig setup, and smart contract approval hygiene tailored to holdings value.",
        "operationId": "security",
        "parameters": [
          {
            "name": "value_tier",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "small",
                "medium",
                "large",
                "institutional"
              ],
              "default": "medium"
            }
          },
          {
            "name": "setup",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "exchange custody"
            },
            "description": "Current custody setup description"
          }
        ],
        "responses": {
          "200": {
            "description": "Security framework with prioritized action list"
          },
          "402": {
            "description": "Payment required."
          }
        },
        "security": [
          {
            "x402": []
          }
        ],
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1,
        "x-agent-chaining": "Response includes Ledger/Trezor hardware wallet links for self-custody"
      }
    },
    "/api/threats": {
      "get": {
        "summary": "Crypto threat intelligence",
        "description": "Current attack vectors, scam patterns, and defense playbook for crypto holders. Includes phishing, drainers, SIM swap, rug pulls, and more.",
        "operationId": "threats",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "all"
            },
            "description": "Threat category: phishing, drainer, sim_swap, rug_pull, flash_loan, or all"
          }
        ],
        "responses": {
          "200": {
            "description": "Threat intelligence with defenses and incident response"
          },
          "402": {
            "description": "Payment required."
          }
        },
        "security": [
          {
            "x402": []
          }
        ],
        "x-agent-use-case": "scheduled",
        "x-price-usd": 0.1
      }
    },
    "/api/exchange": {
      "get": {
        "summary": "Exchange comparison",
        "description": "Compare crypto exchanges by country, priority, and experience level. Includes fees, security record, regulatory status, and fiat on-ramp options.",
        "operationId": "exchange",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "US"
            }
          },
          {
            "name": "priority",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "fees",
                "security",
                "altcoin_selection",
                "beginner_friendly",
                "derivatives",
                "fiat_ramp"
              ],
              "default": "security"
            }
          },
          {
            "name": "experience",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "beginner",
                "intermediate",
                "advanced"
              ],
              "default": "beginner"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Exchange comparison with fee table and security recommendations"
          },
          "402": {
            "description": "Payment required."
          }
        },
        "security": [
          {
            "x402": []
          }
        ],
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1,
        "x-agent-chaining": "Response includes exchange affiliate links matched to experience level (beginner/trader)"
      }
    },
    "/api/tax": {
      "get": {
        "summary": "Crypto tax guidance",
        "description": "Jurisdiction-specific tax obligations, optimization strategies (tax loss harvesting, cost basis methods), and reporting tool recommendations.",
        "operationId": "tax",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "US"
            }
          },
          {
            "name": "activities",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "hold,trade"
            },
            "description": "Comma-separated: hold, trade, defi, mining, staking, nft, business"
          },
          {
            "name": "tax_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Tax year e.g. 2026. Defaults to current year."
          }
        ],
        "responses": {
          "200": {
            "description": "Tax guidance with obligations, strategies, and tool recommendations"
          },
          "402": {
            "description": "Payment required."
          }
        },
        "security": [
          {
            "x402": []
          }
        ],
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.2,
        "x-agent-chaining": "Response includes Koinly/CoinLedger tax software links; supports 20+ countries"
      }
    },
    "/api/onboard": {
      "get": {
        "summary": "First-time buyer onboarding guide",
        "description": "End-to-end guide for new crypto buyers: exchange selection, KYC walkthrough, first purchase, wallet setup, and DCA plan.",
        "operationId": "onboard",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "US"
            }
          },
          {
            "name": "goal",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "invest",
                "use daily",
                "learn",
                "business"
              ],
              "default": "invest"
            }
          },
          {
            "name": "experience",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "complete_beginner",
                "some_knowledge",
                "experienced"
              ],
              "default": "complete_beginner"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Onboarding guide with exchange recommendation and DCA plan"
          },
          "402": {
            "description": "Payment required."
          }
        },
        "security": [
          {
            "x402": []
          }
        ],
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1,
        "x-agent-chaining": "Response includes Coinbase/Gemini/Kraken exchange links; follow with /api/security for self-custody setup"
      }
    },
    "/api/spend": {
      "get": {
        "summary": "Crypto spending guide",
        "description": "Best crypto debit cards, merchant acceptance, gift card platforms, and bill pay options by country.",
        "operationId": "spend",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "US"
            }
          },
          {
            "name": "use_case",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "daily spending"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Spending options with card comparison and tax implications"
          },
          "402": {
            "description": "Payment required."
          }
        },
        "security": [
          {
            "x402": []
          }
        ],
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1
      }
    },
    "/api/banking": {
      "get": {
        "summary": "Crypto-friendly banking guide",
        "description": "Banks and neobanks with high crypto tolerance, de-banking risk assessment, and on/off ramp alternatives by country.",
        "operationId": "banking",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "US"
            }
          },
          {
            "name": "profile",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "personal",
                "business",
                "crypto-heavy",
                "casual"
              ],
              "default": "personal"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Banking recommendations with de-banking risk and on-ramp options"
          },
          "402": {
            "description": "Payment required."
          }
        },
        "security": [
          {
            "x402": []
          }
        ],
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1
      }
    },
    "/api/merchant": {
      "get": {
        "summary": "Merchant crypto payment setup",
        "description": "Compare crypto payment processors for your business type: BTCPay Server, Coinbase Commerce, NOWPayments, Strike, and more.",
        "operationId": "merchant",
        "parameters": [
          {
            "name": "business_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "ecommerce"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "US"
            }
          },
          {
            "name": "integration",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ecommerce",
                "physical_pos",
                "freelance",
                "api"
              ],
              "default": "ecommerce"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Processor comparison with setup guide and settlement strategy"
          },
          "402": {
            "description": "Payment required."
          }
        },
        "security": [
          {
            "x402": []
          }
        ],
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1
      }
    }
  }
}