feat(dev-hub) Api Reference V2

apps/developer-hub/.prettierignore

@@ -11,4 +11,5 @@ build/
 node_modules/
 package.json
 tsconfig*.json
-content/docs/price-feeds/core/use-real-time-data/pull-integration/ton.mdx
+content/docs/price-feeds/core/use-real-time-data/pull-integration/ton.mdx
+content/docs/api-reference/**

apps/developer-hub/README.md

@@ -120,10 +120,96 @@ Update the `meta.json` file in each section to control navigation. Example:
 - Use proper heading hierarchy (h2, h3, etc.)
 - Link to related documentation when relevant
 
+## API Reference Generation
+
+The API reference documentation is automatically generated from OpenAPI specifications using the `scripts/generate-docs.ts` script. This script converts OpenAPI specs (from services like Hermes and Fortuna) into MDX documentation files.
+
+### What It Does
+
+The script performs the following steps:
+
+1. **File Generation**: Uses `fumadocs-openapi` to convert OpenAPI specs into MDX files
+
+   - Each API endpoint becomes a separate MDX file
+   - Files are organized by product (e.g., `pyth-core`, `entropy`) and service (e.g., `hermes`, `fortuna`)
+
+2. **Meta File Generation**: Creates `meta.json` files for navigation
+
+   - Root `meta.json` for the API reference section
+   - Product-level `meta.json` files (e.g., `pyth-core/meta.json`)
+   - Service-level `meta.json` files (e.g., `pyth-core/hermes/meta.json`)
+
+3. **Post-Processing**: Customizes generated files to match our documentation structure
+   - Updates MDX frontmatter titles to use endpoint paths instead of operation IDs
+   - Rewrites `index.mdx` files to use `APICard` components with proper formatting
+
+### When to Run
+
+The script runs automatically during the build process (`pnpm turbo run build`). You typically don't need to run it manually unless:
+
+- You've updated an OpenAPI specification URL
+- You've added a new service to the configuration
+- You want to regenerate docs without doing a full build
+
+### Manual Execution
+
+To run the script manually:
+
+```bash
+pnpm generate:docs
+```
+
+This will:
+
+- Fetch OpenAPI specs from the configured URLs
+- Generate MDX files in `content/docs/api-reference/`
+- Create/update all `meta.json` navigation files
+- Post-process files to customize titles and index pages
+
+### Configuration
+
+To add a new API service, edit `src/lib/openapi.ts` and add an entry to the `products` object:
+
+```typescript
+export const products = {
+  // ... existing services ...
+  newService: {
+    name: "newService",
+    product: "product-category", // e.g., "pyth-core" or "entropy"
+    openApiUrl: "https://api.example.com/docs/openapi.json",
+  },
+};
+```
+
+After adding a new service:
+
+1. Run `pnpm generate:docs` to generate the documentation
+2. The new service will appear in the API reference navigation
+
+### Generated Files
+
+All generated files are written to `content/docs/api-reference/`:
+
+```
+content/docs/api-reference/
+├── meta.json                    # Root navigation
+├── pyth-core/
+│   ├── meta.json               # Product navigation
+│   └── hermes/
+│       ├── meta.json           # Service navigation
+│       ├── index.mdx           # Service overview page
+│       └── *.mdx               # Individual endpoint pages
+└── entropy/
+    └── ...
+```
+
+**Important**: Generated files should not be edited manually. Any changes will be overwritten the next time the script runs. If you need to customize the documentation, modify the OpenAPI specification or the generation script itself.
+
 ## Available Commands
 
 - `pnpm turbo run start:dev` - Start development server
-- `pnpm turbo run build` - Build the project
+- `pnpm turbo run build` - Build the project (includes API reference generation)
+- `pnpm generate:docs` - Generate API reference documentation manually
 - `pnpm turbo run fix:format` - Format code with Prettier
 - `pnpm turbo run fix:lint:eslint` - Fix ESLint issues
 - `pnpm turbo run test:format` - Check formatting

apps/developer-hub/content/docs/openapi/fortuna/chain_ids.mdx → apps/developer-hub/content/docs/api-reference/entropy/fortuna/chain_ids.mdx

@@ -1,5 +1,5 @@
 ---
-title: Get the list of supported chain ids
+title: "/v1/chains"
 description: Get the list of supported chain ids
 full: true
 _openapi:
@@ -14,9 +14,4 @@ _openapi:
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
 
-<APIPage
-  document={"https://fortuna-staging.dourolabs.app/docs/openapi.json"}
-  operations={[{ path: "/v1/chains", method: "get" }]}
-  webhooks={[]}
-  hasHead={false}
-/>
+<APIPage document={"https://fortuna-staging.dourolabs.app/docs/openapi.json"} operations={[{"path":"/v1/chains","method":"get"}]} webhooks={[]} hasHead={false} />

apps/developer-hub/content/docs/openapi/fortuna/explorer.mdx → apps/developer-hub/content/docs/api-reference/entropy/fortuna/explorer.mdx

@@ -1,5 +1,5 @@
 ---
-title: Returns the logs of all requests captured by the keeper.
+title: "/v1/logs"
 description: >-
   Returns the logs of all requests captured by the keeper.
 
@@ -32,9 +32,4 @@ _openapi:
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
 
-<APIPage
-  document={"https://fortuna-staging.dourolabs.app/docs/openapi.json"}
-  operations={[{ path: "/v1/logs", method: "get" }]}
-  webhooks={[]}
-  hasHead={false}
-/>
+<APIPage document={"https://fortuna-staging.dourolabs.app/docs/openapi.json"} operations={[{"path":"/v1/logs","method":"get"}]} webhooks={[]} hasHead={false} />

apps/developer-hub/content/docs/api-reference/entropy/fortuna/index.mdx

@@ -0,0 +1,9 @@
+---
+title: Overview
+---
+
+<APICards>
+  <APICard href="/api-reference/entropy/fortuna/chain_ids" title="/v1/chains" method="GET" description="Get the list of supported chain ids" />
+  <APICard href="/api-reference/entropy/fortuna/revelation" title="/v1/chains/{chain_id}/revelations/{sequence}" method="GET" description="Reveal the random value for a given sequence number and blockchain." />
+  <APICard href="/api-reference/entropy/fortuna/explorer" title="/v1/logs" method="GET" description="Returns the logs of all requests captured by the keeper." />
+</APICards>

apps/developer-hub/content/docs/api-reference/entropy/fortuna/meta.json

@@ -0,0 +1,9 @@
+{
+  "title": "Fortuna",
+  "pages": [
+    "index",
+    "chain_ids",
+    "revelation",
+    "explorer"
+  ]
+}

apps/developer-hub/content/docs/openapi/fortuna/revelation.mdx → apps/developer-hub/content/docs/api-reference/entropy/fortuna/revelation.mdx

@@ -1,5 +1,5 @@
 ---
-title: Reveal the random value for a given sequence number and blockchain.
+title: "/v1/chains/{chain_id}/revelations/{sequence}"
 description: >-
   Reveal the random value for a given sequence number and blockchain.
 
@@ -44,11 +44,4 @@ _openapi:
 
 {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
 
-<APIPage
-  document={"https://fortuna-staging.dourolabs.app/docs/openapi.json"}
-  operations={[
-    { path: "/v1/chains/{chain_id}/revelations/{sequence}", method: "get" },
-  ]}
-  webhooks={[]}
-  hasHead={false}
-/>
+<APIPage document={"https://fortuna-staging.dourolabs.app/docs/openapi.json"} operations={[{"path":"/v1/chains/{chain_id}/revelations/{sequence}","method":"get"}]} webhooks={[]} hasHead={false} />

apps/developer-hub/content/docs/api-reference/entropy/meta.json

@@ -0,0 +1,6 @@
+{
+  "title": "Entropy",
+  "pages": [
+    "fortuna"
+  ]
+}

apps/developer-hub/content/docs/api-reference/index.mdx

@@ -0,0 +1,34 @@
+---
+title: API Reference
+description: Complete API reference for Pyth Network services
+---
+
+import { IntegrationCard } from "../../../src/components/IntegrationCard";
+import { DiceSix, Database } from "@phosphor-icons/react/dist/ssr";
+
+Welcome to the Pyth Network API Reference. Explore REST APIs for our core services.
+
+## Entropy
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+  <IntegrationCard
+    href="/api-reference/entropy/fortuna"
+    title="Fortuna"
+    description="Random number generation API with callback support"
+    icon={<DiceSix size={16} />}
+    colorScheme="green"
+  />
+</div>
+
+## Pyth Core
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+  <IntegrationCard
+    href="/api-reference/pyth-core/hermes"
+    title="Hermes"
+    description="REST API for accessing price feeds and updates"
+    icon={<Database size={16} />}
+    colorScheme="blue"
+  />
+</div>
+

apps/developer-hub/content/docs/api-reference/meta.json

@@ -0,0 +1,9 @@
+{
+  "root": true,
+  "title": "API Reference",
+  "icon": "Code",
+  "pages": [
+    "entropy",
+    "pyth-core"
+  ]
+}

apps/developer-hub/content/docs/api-reference/pyth-core/hermes/get_price_feed.mdx

@@ -0,0 +1,33 @@
+---
+title: "/api/get_price_feed"
+description: >-
+  **Deprecated: use /v2/updates/price/{publish_time} instead**
+
+
+  Get a price update for a price feed with a specific timestamp
+
+
+  Given a price feed id and timestamp, retrieve the Pyth price update closest to
+  that timestamp.
+full: true
+_openapi:
+  method: GET
+  route: /api/get_price_feed
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >-
+          **Deprecated: use /v2/updates/price/{publish_time} instead**
+
+
+          Get a price update for a price feed with a specific timestamp
+
+
+          Given a price feed id and timestamp, retrieve the Pyth price update
+          closest to that timestamp.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+<APIPage document={"https://hermes.pyth.network/docs/openapi.json"} operations={[{"path":"/api/get_price_feed","method":"get"}]} webhooks={[]} hasHead={false} />

apps/developer-hub/content/docs/api-reference/pyth-core/hermes/get_vaa.mdx

@@ -0,0 +1,33 @@
+---
+title: "/api/get_vaa"
+description: >-
+  **Deprecated: use /v2/updates/price/{publish_time} instead**
+
+
+  Get a VAA for a price feed with a specific timestamp
+
+
+  Given a price feed id and timestamp, retrieve the Pyth price update closest to
+  that timestamp.
+full: true
+_openapi:
+  method: GET
+  route: /api/get_vaa
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >-
+          **Deprecated: use /v2/updates/price/{publish_time} instead**
+
+
+          Get a VAA for a price feed with a specific timestamp
+
+
+          Given a price feed id and timestamp, retrieve the Pyth price update
+          closest to that timestamp.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+<APIPage document={"https://hermes.pyth.network/docs/openapi.json"} operations={[{"path":"/api/get_vaa","method":"get"}]} webhooks={[]} hasHead={false} />

apps/developer-hub/content/docs/api-reference/pyth-core/hermes/get_vaa_ccip.mdx

@@ -0,0 +1,39 @@
+---
+title: "/api/get_vaa_ccip"
+description: >-
+  **Deprecated: use /v2/updates/price/{publish_time} instead**
+
+
+  Get a VAA for a price feed using CCIP
+
+
+  This endpoint accepts a single argument which is a hex-encoded byte string of
+  the following form:
+
+  `<price feed id (32 bytes> <publish time as unix timestamp (8 bytes, big
+  endian)>`
+full: true
+_openapi:
+  method: GET
+  route: /api/get_vaa_ccip
+  toc: []
+  structuredData:
+    headings: []
+    contents:
+      - content: >-
+          **Deprecated: use /v2/updates/price/{publish_time} instead**
+
+
+          Get a VAA for a price feed using CCIP
+
+
+          This endpoint accepts a single argument which is a hex-encoded byte
+          string of the following form:
+
+          `<price feed id (32 bytes> <publish time as unix timestamp (8 bytes,
+          big endian)>`
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+<APIPage document={"https://hermes.pyth.network/docs/openapi.json"} operations={[{"path":"/api/get_vaa_ccip","method":"get"}]} webhooks={[]} hasHead={false} />

apps/developer-hub/content/docs/api-reference/pyth-core/hermes/index.mdx

@@ -0,0 +1,18 @@
+---
+title: Overview
+---
+
+<APICards>
+  <APICard href="/api-reference/pyth-core/hermes/get_price_feed" title="/api/get_price_feed" method="GET" description="Get a price update for a price feed with a specific timestamp Given a price feed id and timestamp, retrieve the Pyth price update closest to that timestamp." />
+  <APICard href="/api-reference/pyth-core/hermes/get_vaa" title="/api/get_vaa" method="GET" description="Get a VAA for a price feed with a specific timestamp Given a price feed id and timestamp, retrieve the Pyth price update closest to that timestamp." />
+  <APICard href="/api-reference/pyth-core/hermes/get_vaa_ccip" title="/api/get_vaa_ccip" method="GET" description="Get a VAA for a price feed using CCIP This endpoint accepts a single argument which is a hex-encoded byte string of the following form: `<price feed id (32 bytes> <publish time as unix timestamp (8 bytes, big endian)>`" />
+  <APICard href="/api-reference/pyth-core/hermes/latest_price_feeds" title="/api/latest_price_feeds" method="GET" description="Get the latest price updates by price feed id." />
+  <APICard href="/api-reference/pyth-core/hermes/latest_vaas" title="/api/latest_vaas" method="GET" description="Get VAAs for a set of price feed ids." />
+  <APICard href="/api-reference/pyth-core/hermes/price_feed_ids" title="/api/price_feed_ids" method="GET" description="Get the set of price feed IDs." />
+  <APICard href="/api-reference/pyth-core/hermes/price_feeds_metadata" title="/v2/price_feeds" method="GET" description="Get the set of price feeds." />
+  <APICard href="/api-reference/pyth-core/hermes/latest_price_updates" title="/v2/updates/price/latest" method="GET" description="Get the latest price updates by price feed id." />
+  <APICard href="/api-reference/pyth-core/hermes/price_stream_sse_handler" title="/v2/updates/price/stream" method="GET" description="SSE route handler for streaming price updates." />
+  <APICard href="/api-reference/pyth-core/hermes/timestamp_price_updates" title="/v2/updates/price/{publish_time}" method="GET" description="Get the latest price updates by price feed id." />
+  <APICard href="/api-reference/pyth-core/hermes/latest_publisher_stake_caps" title="/v2/updates/publisher_stake_caps/latest" method="GET" description="Get the most recent publisher stake caps update data." />
+  <APICard href="/api-reference/pyth-core/hermes/latest_twaps" title="/v2/updates/twap/{window_seconds}/latest" method="GET" description="Get the latest TWAP by price feed id with a custom time window." />
+</APICards>