docs: add API overview and Convert API migration guide (#224)

- ApiOverview.mdx: add "API Entry Points" section explaining chain-scoped
  vs cross-chain endpoints and BFF API (frontend-only, not for third-party
  integrations); add vePENDLE deprecation notice pointing to sPENDLE

- HostedSdk.mdx: add "Migrating from individual endpoints to Convert"
  section with a full mapping table (old endpoint path → equivalent Convert
  tokensIn/tokensOut), plus a "Which version should I use?" callout
  recommending v3 (POST) for new integrations

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: UncleGrandpa925

docs/pendle-v2/Developers/Backend/ApiOverview.mdx

@@ -37,6 +37,36 @@ Pendle's API consists of two complementary components:
 
 📖 [View Backend API Documentation](https://api-v2.pendle.finance/core/docs)
 
+## API Entry Points
+
+All public endpoints are served under `https://api-v2.pendle.finance/core` and follow one of two routing patterns:
+
+### Chain-scoped endpoints — `/v1/{chainId}/...`
+
+These are the original per-chain routes. They remain fully functional and are a safe choice for chain-specific integrations:
+
+| Example | Description |
+|---------|-------------|
+| `GET /v1/{chainId}/markets` | Markets on a specific chain |
+| `GET /v1/{chainId}/prices/assets/all` | Asset prices on a specific chain |
+| `GET /v1/{chainId}/sdk/swap` | Swap transaction payload for a specific chain |
+
+### Cross-chain endpoints — `/v1/...`
+
+Newer endpoints that return data across all chains in a single request. Preferred for new integrations:
+
+| Example | Description |
+|---------|-------------|
+| `GET /v1/markets/all` | All markets across all chains |
+| `GET /v1/assets/all` | All assets across all chains |
+| `GET /v1/prices/assets` | Asset prices across all chains |
+
+For new integrations, prefer cross-chain endpoints where available — they reduce the number of calls needed when working with multiple chains.
+
+### BFF API — `https://api-v2.pendle.finance/bff`
+
+The BFF (Backend for Frontend) API powers the official Pendle web app. It is **not intended for third-party integrations**: endpoints may change or be removed without notice. For third-party use, always use the `/core` API documented here.
+
 ## Rate Limiting
 
 All Pendle API endpoints are rate-limited to ensure service stability and fair usage.
@@ -166,8 +196,13 @@ The `X-Ratelimit-Limit: 100` value in this case is simply a default header from
 
 :::
 
-## API Updates and deprecation notice
-- **Deprecation Notice**: Breaking changes announced at least 30 days in advance, follow [Telegram Developer Channel](https://t.me/pendledevelopers) for announcements
+## API Updates and Deprecation
+
+- **Deprecation Notice**: Breaking changes are announced at least 30 days in advance. Follow the [Telegram Developer Channel](https://t.me/pendledevelopers) for announcements.
+
+### vePENDLE Deprecation
+
+vePENDLE has been deprecated and replaced by **sPENDLE**. All endpoints listed under the **Ve Pendle** tag in the [Swagger documentation](https://api-v2.pendle.finance/core/docs) are deprecated — they remain accessible but will not be updated to reflect the new sPENDLE staking system.
 
 ## Code Examples and Resources
 

docs/pendle-v2/Developers/Backend/HostedSdk.mdx

@@ -469,3 +469,30 @@ When an endpoint has an `additionalData` field, users can pass in some fields to
 For example, the **swap** action has `additionalData` with two available fields: `impliedApy` and `effectiveApy`. If the query parameters have `additionalData=impliedApy`, the response will have the implied APY before and after the swap action.
 
 For additional usage, please refer to our external swagger to explore more.
+
+## Migrating from individual endpoints to Convert
+
+The Convert API replaces all of the individual SDK endpoints (`/swap`, `/add-liquidity`, `/mint`, `/redeem`, etc.). The table below maps each old endpoint to the equivalent Convert call.
+
+| Old endpoint | Convert equivalent |
+|---|---|
+| `GET /v2/sdk/{chainId}/markets/{market}/swap` | `tokensIn=[token/PT/YT]`, `tokensOut=[token/PT/YT]` |
+| `GET /v2/sdk/{chainId}/markets/{market}/add-liquidity` | `tokensIn=[token]`, `tokensOut=[LP]` (standard) or `tokensOut=[LP,YT]` (ZPI) |
+| `GET /v2/sdk/{chainId}/markets/{market}/add-liquidity-dual` | `tokensIn=[token,PT]`, `tokensOut=[LP]` |
+| `GET /v2/sdk/{chainId}/markets/{market}/remove-liquidity` | `tokensIn=[LP]`, `tokensOut=[token]` |
+| `GET /v2/sdk/{chainId}/markets/{market}/remove-liquidity-dual` | `tokensIn=[LP]`, `tokensOut=[token,PT]` |
+| `GET /v2/sdk/{chainId}/mint` | `tokensIn=[token]`, `tokensOut=[PT,YT]` |
+| `GET /v2/sdk/{chainId}/redeem` | `tokensIn=[PT,YT]` (or just `[PT]` after expiry), `tokensOut=[token]` |
+| `GET /v2/sdk/{chainId}/mint-sy` | `tokensIn=[token]`, `tokensOut=[SY]` |
+| `GET /v2/sdk/{chainId}/redeem-sy` | `tokensIn=[SY]`, `tokensOut=[token]` |
+| `GET /v2/sdk/{chainId}/markets/{market}/transfer-liquidity` | `tokensIn=[LP,PT,YT]` (any subset), `tokensOut=[destination LP]` |
+| `GET /v2/sdk/{chainId}/markets/{market}/roll-over-pt` | `tokensIn=[source PT]`, `tokensOut=[destination PT]` |
+| `GET /v2/sdk/{chainId}/markets/{market}/exit-positions` | `tokensIn=[LP,PT,YT]` (any subset), `tokensOut=[token]` |
+
+### Which version should I use?
+
+Use **v3 (POST `/v3/sdk/{chainId}/convert`)** for new integrations. It accepts a JSON body with a typed `inputs` array instead of comma-separated query strings, which is easier to construct programmatically.
+
+Use **v2 (GET `/v2/sdk/{chainId}/convert`)** if you need a fully query-parameter-based URL (e.g. for simple curl testing or when an HTTP client doesn't support request bodies on GET).
+
+Both variants execute the same logic and return the same response.