doc: Alpha Token API

Consensys · Jan 10, 2025 · 21d1fd8 · 21d1fd8
1 parent da6e513
commit 21d1fd8
Show file tree

Hide file tree

Showing 10 changed files with 311 additions and 37 deletions.
diff --git a/docs/api/index.mdx → docs/api/reference/index.mdx b/docs/api/index.mdx → docs/api/reference/index.mdx
@@ -9,8 +9,8 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 Linea supports the standard Ethereum JSON-RPC API methods, meaning the developer experience is
-identical to building on Ethereum itself. However, some methods differ to Ethereum — find them in 
-the [reference section](./reference/eth-sendrawtransaction.mdx).
+identical to building on Ethereum itself. However, some methods differ to Ethereum, and are covered
+in this section.
 
 :::info
 View the full list of Linea methods in the
@@ -20,13 +20,13 @@ View the full list of Linea methods in the
 You must connect to an RPC endpoint when making calls to the Linea blockchain. Use one or more of the
 following options:
 
-- **Run your own node**: Either [run your own node by setting it up yourself](../get-started/how-to/run-a-node/index.mdx), or
-    [use a node provider](../get-started/tooling/node-providers/index.mdx).
-    We recommend running [Linea Besu](../get-started/how-to/run-a-node/linea-besu.mdx) if you want to run a node yourself and interact with the
+- **Run your own node**: Either [run your own node by setting it up yourself](../../get-started/how-to/run-a-node/index.mdx), or
+    [use a node provider](../../get-started/tooling/node-providers/index.mdx).
+    We recommend running [Linea Besu](../../get-started/how-to/run-a-node/linea-besu.mdx) if you want to run a node yourself and interact with the
     blockchain.
-- **Connect to a private RPC endpoint**: [Connect to a blockchain infrastructure provider](../get-started/tooling/node-providers/index.mdx#private-rpc-endpoints)
+- **Connect to a private RPC endpoint**: [Connect to a blockchain infrastructure provider](../../get-started/tooling/node-providers/index.mdx#private-rpc-endpoints)
     such as Infura or Alchemy. Multiple providers offer free tier access.
-- **Use a public endpoint**: [Public endpoints](../get-started/tooling/node-providers/index.mdx#public-rpc-endpoints) are
+- **Use a public endpoint**: [Public endpoints](../../get-started/tooling/node-providers/index.mdx#public-rpc-endpoints) are
     free to use but are rate limited and not suitable for production environments.
 
 ## Make calls
@@ -37,7 +37,7 @@ the endpoint with whichever endpoint you prefer.
 In the examples, replace `<YOUR-API-KEY>` with your actual Infura API key.
 
 :::info
-View the [list of node providers](../get-started/tooling/node-providers/index.mdx) if you require an endpoint.
+View the [list of node providers](../../get-started/tooling/node-providers/index.mdx) if you require an endpoint.
 :::
 
 

diff --git a/docs/api/token-api.mdx b/docs/api/token-api.mdx
@@ -0,0 +1,256 @@
+---
+title: Token API
+image: /img/socialCards/token-api.jpg
+---
+
+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 associated activity 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.
+We are looking for your feedback on this new service — please reach out to us on [Discord](https://discord.com/invite/linea) 
+in the [#developer-chat](https://discord.com/channels/1141419161893998702/1141419163223593024) 
+channel.
+:::
+
+The Token API's key uses cases include:
+
+- Building automated trading bots
+- Creating token monitoring dashboards
+- Performing onchain data analysis
+- DeFi application integration
+- Wallet and transaction tracking
+
+## Data sources
+
+### Data collection
+
+Data is collected from multiple sources:
+
+1. **Onchain data**
+ - Smart contract state (name, symbol, decimals)
+
+2. **External sources**
+ - [CoinGecko](https://www.coingecko.com/en/api)
+ - [MetaMask Token API](https://docs.cx.metamask.io/docs/token-v2/)
+ - [MetaMask Price API](https://docs.cx.metamask.io/docs/price/)
+ - [Pond.fun](https://pond.fun/)
+ - [Dune Analytics](https://dune.com/)
+
+### Data updates
+
+The API data updates at various intervals, depending on the data type:
+
+- Token detection and metadata: every two hours
+- Historical prices: every hour
+- Current prices: every five minutes
+
+## API endpoints
+
+### Tokens
+
+These endpoints provide information about tokens on Linea when available, including their metadata, 
+prices, and trading activity.
+
+#### Get `/api/tokens`
+
+Retrieve a 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:**
+
+<table>
+  <thead>
+    <tr>
+      <th>Parameter</th>
+      <th>Type</th>
+      <th>Required</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>`contractAddress`</td>
+      <td>string</td>
+      <td>Yes</td>
+      <td>Token address</td>
+    </tr>
+  </tbody>
+</table>
+
+  <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/new-gems`
+
+Retrieve recently bonded tokens.
+
+<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`
+
+Retrieve the 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 token price bot
+
+```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) in the [#developer-chat](https://discord.com/channels/1141419161893998702/1141419163223593024) channel.
diff --git a/docs/get-started/build/ethereum-differences.mdx b/docs/get-started/build/ethereum-differences.mdx
@@ -102,4 +102,4 @@ The point evaluation precompile was introduced in [EIP-4844](https://eips.ethere
 ## JSON RPC API
 
 Linea uses the standard Ethereum JSON RPC API methods. However, in a few cases, methods differ from 
-those on Ethereum. These methods are documented in the [reference section](../../api/index.mdx).
+those on Ethereum. These methods are documented in the [reference section](../../api/reference/index.mdx).
diff --git a/docs/get-started/how-to/connect-wallet.mdx b/docs/get-started/how-to/connect-wallet.mdx
@@ -1,6 +1,9 @@
 ---
 title: Connect a wallet to your dapp
-description: Learn how to connect a wallet to your dapp so users can interact with your contracts
+description: >-
+  Learn how to connect a wallet to your dapp so users can interact with your
+  contracts
+image: /img/socialCards/connect-a-wallet-to-your-dapp.jpg
 ---
 
 Enabling users' wallets to connect to your dapp is critical, since it's the only way they can

diff --git a/docs/get-started/how-to/run-a-node/index.mdx b/docs/get-started/how-to/run-a-node/index.mdx
@@ -11,7 +11,7 @@ This section guides you through running a Linea node using various compatible Et
 
 :::info important
 While Linea supports multiple clients, only Linea Besu currently allows you to access Linea-specific
-features, such as using [Linea methods](../../../api/index.mdx) (for example, `linea_estimateGas`)
+features, such as using [Linea methods](../../../api/reference/index.mdx) (for example, `linea_estimateGas`)
 or calling methods using the `finalized` tag.
 
 Linea Besu is recommended for infrastructure providers and operators who intend to run a Linea
@@ -41,7 +41,7 @@ to Linea-specific features.
     </tr>
     <tr>
       <td>[Linea Besu](./linea-besu.mdx)</td>
-      <td>Besu client with plugins that implement Linea-specific features, such as <a href="../../../api/index.mdx">API methods</a> and <a href="../finalized-block.mdx">finalized</a> tag.</td>
+      <td>Besu client with plugins that implement Linea-specific features, such as <a href="../../../api/reference/index.mdx">API methods</a> and <a href="../finalized-block.mdx">finalized</a> tag.</td>
       <td>✅</td>
     </tr>
     <tr>

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -141,9 +141,9 @@ const config = {
           },
           {
             type: "doc",
-            docId: "api/index",
+            docId: "api/linea-smart-contracts/linearollup",
             position: "left",
-            label: "API & SDK",
+            label: "APIs & SDK",
           },
           {
             type: "doc",

diff --git a/mlc_config.json b/mlc_config.json
@@ -32,7 +32,15 @@
       },
       {
         "pattern": "https://portfolio.metamask.io/bridge"
+      },
+      {
+        "pattern": "https://www.coingecko.com/en/api"
+      },
+      {
+        "pattern": "https://dune.com/"
+      },
+      {
+        "pattern": "https://dune.com/queries/4396527"
       }
     ]
   }
-
diff --git a/redirects.json b/redirects.json
@@ -83,7 +83,7 @@
         ]
     },
     {
-        "to": "/api",
+        "to": "/api/reference",
         "from": [
             "/build-on-linea/quickstart/rpc",
             "/developers/guides/linea-api",