doc: Alpha Token API

docs/api/token-api.mdx

@@ -0,0 +1,226 @@
+---
+title: (Alpha) Token API
+image: /img/socialCards/linea-sdk.jpg
+---
+
+## Overview
+
+The Token API provides comprehensive programmatic access to token data on the Linea network.
+This API is designed for developers, builders and analysts who need detailed information about ERC-20 tokens and their activities on Linea.
+
+:::warning[Alpha Version Disclaimer]
+Linea's Token API is an alpha version and is subject to breaking changes.
+We recommend using it for testing and development purposes only.
+:::
+
+### Key use cases
+
+- Building automated trading bots
+- Creating token monitoring dashboards
+- Performing on chain data analysis
+- DeFi application integration
+- Wallet and transaction tracking
+
+## Data sources
+
+### Data collection
+
+Data is collected from multiple sources:
+
+1. **On chain Data**
+ - Smart contract state (name, symbol, decimals)
+
+2. **External Sources**
+ - [CoinGecko](https://www.coingecko.com/en/api)
+ - [MetaMask Token](https://docs.cx.metamask.io/docs/token-v2/)
+ - [MetaMask Price](https://docs.cx.metamask.io/docs/price/)
+ - [Pond.fun](https://pond.fun/)
+ - [Dune Analytics](https://dune.com/)
+
+### Data updates
+
+- Periodic synchronization (every 2 hours) for token detection and metadata
+- Periodic synchronization (every 1 hour) for historical prices
+- Periodic synchronization (every 5 minutes) for current prices
+
+## API endpoints
+
+### Tokens
+
+#### GET `/api/tokens`
+
+Retrieve the list of all available tokens on Linea.
+
+<details>
+  <summary>**Response**</summary>
+  ```json
+  [
+    {
+      "name": "Wrapped Ether",
+      "symbol": "WETH",
+      "decimals": 18,
+      "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png",
+      "contractAddress": "0xe5d7c2a44ffddf6b295a15c148167daaaf5cf34f",
+      "currentPrice": "3321.74000000000000",
+      "priceUpdatedAt": "2025-01-09T09:36:02.194Z",
+      "info": {
+        "prices": [
+          {
+            "price": "3321.74000000000000",
+            "date": "2025-01-09T09:00:00.000Z"
+          }
+        ],
+        "sells": 3279,
+        "buys": 3722,
+        "graduatedAt": null
+      }
+    }
+  ]
+  ```
+</details>
+
+#### GET `/api/tokens/{contractAddress}`
+
+Retrieve detailed information for a specific token.
+
+**Parameters**
+
+| Parameter         | Type   | Required | Description     |
+|-------------------|--------|----------|-----------------|
+| contractAddress   | string | Yes      | Token address   |
+
+  <details>
+    <summary>**Response**</summary>
+    ```json
+    {
+      "name": "Wrapped Ether",
+      "symbol": "WETH",
+      "decimals": 18,
+      "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png",
+      "contractAddress": "0xe5d7c2a44ffddf6b295a15c148167daaaf5cf34f",
+      "currentPrice": "3321.74000000000000",
+      "priceUpdatedAt": "2025-01-09T09:36:02.194Z",
+      "info": {
+          "prices": [
+              {
+                  "price": "3321.74000000000000",
+                  "date": "2025-01-09T09:00:00.000Z"
+              }
+          ],
+          "sells": 3279,
+          "buys": 3722,
+          "graduatedAt": null
+      }
+    }
+    ```
+  </details>
+
+### Prices
+
+#### GET `/api/tokens/new-gems`
+
+Retrieve recently bounded tokens from the [Pond.fun](https://pond.fun/) launchpad.
+
+<details>
+  <summary>**Response**</summary>
+  ```json
+  [
+    {
+      "name": "CatWifCap",
+      "symbol": "CWC",
+      "decimals": 18,
+      "logo": "https://d12kvghf2eznx1.cloudfront.net/tokens/images/d0a931cd-7982-47e4-86c7-74be11ab0b09",
+      "contractAddress": "0x092b9e25a7d143c83d44c27194f5cee7c1150f22",
+      "currentPrice": "0.00013412000000",
+      "priceUpdatedAt": "2025-01-09T09:45:04.799Z",
+      "info": {
+          "prices": [
+              {
+                  "price": "0.00013412000000",
+                  "date": "2025-01-09T09:00:00.000Z"
+              }
+          ],
+          "sells": 0,
+          "buys": 0,
+          "graduatedAt": "2024-12-01T18:19:42.095Z"
+      }
+    }
+  ]
+  ```
+</details>
+#### GET `/api/tokens/most-swapped`
+
+Retrieves most swapped tokens over the last 24 hours (from the [corresponding Dune query](https://dune.com/queries/4396527)).
+
+  <details>
+    <summary>**Response**</summary>
+    ```json
+    [
+      {
+        "name": "Foxy",
+        "symbol": "FOXY",
+        "decimals": 18,
+        "logo": "https://i.ibb.co/MSKkFbf/logo.png",
+        "contractAddress": "0x5fbdf89403270a1846f5ae7d113a989f850d1566",
+        "currentPrice": "0.01080016000000",
+        "priceUpdatedAt": "2025-01-09T09:50:05.106Z",
+        "info": {
+            "prices": [
+                {
+                    "price": "0.01078276000000",
+                    "date": "2025-01-09T09:00:00.000Z"
+                }
+            ],
+            "sells": 219,
+            "buys": 212,
+            "graduatedAt": null
+        }
+      }
+    ]
+    ```
+</details>
+
+## Usage examples
+
+### Simple trading bot creation
+
+```typescript
+async function monitorPriceChange(contractAddress: string, threshold: number) {
+  const BASE_URL = 'https://not.live.yet';
+  const initialPrice = await fetch(`${BASE_URL}/api/tokens/${contractAddress}`).then(r => r.json());
+
+  setInterval(async () => {
+    const currentPrice = await fetch(`${BASE_URL}/api/tokens/${contractAddress}`).then(r => r.json());
+    const priceChange = (currentPrice.price.usd - initialPrice.price.usd) / initialPrice.price.usd;
+
+    if (Math.abs(priceChange) > threshold) {
+      // Execute trading strategy
+      console.log(`Price changed by ${priceChange}% - Trading signal`);
+    }
+  }, 60000); // Check every minute
+}
+```
+
+## Best practices
+
+1. **Rate Limiting**
+ - This is an alpha version, with a low rate limit
+ - Cache static data
+
+2. **Error Handling**
+ - Always check HTTP status of responses
+ - Implement retry with exponential backoff
+ - Validate token addresses before requests
+
+3. **Performance**
+ - (Not available yet) Use pagination for large lists
+ - Implement local caching when appropriate
+
+## Security considerations
+
+- Validate all input parameters
+- Sanitize response data
+
+## Support and feedback
+
+For technical support or feature requests, reach out to us on [Discord](https://discord.com/invite/linea).

sidebars.js

@@ -1,4 +1,4 @@
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+/** @type {import("@docusaurus/plugin-content-docs").SidebarsConfig} */
 const sidebars = {
   getStartedSidebar: [
     {
@@ -573,6 +573,7 @@ const sidebars = {
         },
       ],
     },
+    "api/token-api",
   ],
   technologySidebar: [
     "technology/architecture",