Skip to content

Commit 3bf9051

Browse files
alainnclsalainncls
committed
doc: Alpha Token API
1 parent da6e513 commit 3bf9051

File tree

10 files changed

+374
-37
lines changed

10 files changed

+374
-37
lines changed

‎docs/api/index.mdx renamed to ‎docs/api/reference/index.mdx

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ import Tabs from '@theme/Tabs';
99
import TabItem from '@theme/TabItem';
1010

1111
Linea supports the standard Ethereum JSON-RPC API methods, meaning the developer experience is
12-
identical to building on Ethereum itself. However, some methods differ to Ethereum — find them in
13-
the [reference section](./reference/eth-sendrawtransaction.mdx).
12+
identical to building on Ethereum itself. However, some methods differ to Ethereum, and are covered
13+
in this section.
1414

1515
:::info
1616
View the full list of Linea methods in the
@@ -20,13 +20,13 @@ View the full list of Linea methods in the
2020
You must connect to an RPC endpoint when making calls to the Linea blockchain. Use one or more of the
2121
following options:
2222

23-
- **Run your own node**: Either [run your own node by setting it up yourself](../get-started/how-to/run-a-node/index.mdx), or
24-
[use a node provider](../get-started/tooling/node-providers/index.mdx).
25-
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
23+
- **Run your own node**: Either [run your own node by setting it up yourself](../../get-started/how-to/run-a-node/index.mdx), or
24+
[use a node provider](../../get-started/tooling/node-providers/index.mdx).
25+
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
2626
blockchain.
27-
- **Connect to a private RPC endpoint**: [Connect to a blockchain infrastructure provider](../get-started/tooling/node-providers/index.mdx#private-rpc-endpoints)
27+
- **Connect to a private RPC endpoint**: [Connect to a blockchain infrastructure provider](../../get-started/tooling/node-providers/index.mdx#private-rpc-endpoints)
2828
such as Infura or Alchemy. Multiple providers offer free tier access.
29-
- **Use a public endpoint**: [Public endpoints](../get-started/tooling/node-providers/index.mdx#public-rpc-endpoints) are
29+
- **Use a public endpoint**: [Public endpoints](../../get-started/tooling/node-providers/index.mdx#public-rpc-endpoints) are
3030
free to use but are rate limited and not suitable for production environments.
3131

3232
## Make calls
@@ -37,7 +37,7 @@ the endpoint with whichever endpoint you prefer.
3737
In the examples, replace `<YOUR-API-KEY>` with your actual Infura API key.
3838

3939
:::info
40-
View the [list of node providers](../get-started/tooling/node-providers/index.mdx) if you require an endpoint.
40+
View the [list of node providers](../../get-started/tooling/node-providers/index.mdx) if you require an endpoint.
4141
:::
4242

4343

‎docs/api/token-api.mdx

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
---
2+
title: Token API
3+
image: /img/socialCards/token-api.jpg
4+
---
5+
6+
The Token API provides comprehensive programmatic access to token data on the Linea network.
7+
This API is designed for developers, builders and analysts who need detailed information about
8+
ERC-20 tokens and associated activity on Linea.
9+
10+
:::warning[Alpha Version Disclaimer]
11+
Linea's Token API is an alpha version and is subject to breaking changes.
12+
We recommend using it for testing and development purposes only.
13+
We are looking for your feedback on this new service—please reach out to us on [Discord](https://discord.com/invite/linea)
14+
in the [#developer-chat](https://discord.com/channels/1141419161893998702/1141419163223593024)
15+
channel.
16+
:::
17+
18+
The Token API's key uses cases include:
19+
20+
- Building automated trading bots
21+
- Creating token monitoring dashboards
22+
- Performing onchain data analysis
23+
- DeFi application integration
24+
- Wallet and transaction tracking
25+
26+
## Data sources
27+
28+
### Data collection
29+
30+
Data is collected from multiple sources:
31+
32+
1. **Onchain data**
33+
- Smart contract state (name, symbol, decimals)
34+
35+
2. **External sources**
36+
- [CoinGecko](https://www.coingecko.com/en/api)
37+
- [MetaMask Token API](https://docs.cx.metamask.io/docs/token-v2/)
38+
- [MetaMask Price API](https://docs.cx.metamask.io/docs/price/)
39+
- [Pond.fun](https://pond.fun/)
40+
- [Dune Analytics](https://dune.com/)
41+
42+
### Data updates
43+
44+
The API data updates at various intervals, depending on the data type:
45+
46+
- Token detection and metadata: every two hours
47+
- Historical prices: every hour
48+
- Current prices: every five minutes
49+
50+
## API endpoints
51+
52+
### Tokens
53+
54+
These endpoints provide information about tokens on Linea when available, including their metadata,
55+
prices, and trading activity.
56+
57+
#### Get `/api/tokens`
58+
59+
Retrieve a list of all available tokens on Linea.
60+
61+
<details>
62+
<summary>**Response**</summary>
63+
64+
```json
65+
[
66+
{
67+
"name": "Wrapped Ether",
68+
"symbol": "WETH",
69+
"decimals": 18,
70+
"logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png",
71+
"contractAddress": "0xe5d7c2a44ffddf6b295a15c148167daaaf5cf34f",
72+
"currentPrice": "3321.74000000000000",
73+
"priceUpdatedAt": "2025-01-09T09:36:02.194Z",
74+
"info": {
75+
"prices": [
76+
{
77+
"price": "3321.74000000000000",
78+
"date": "2025-01-09T09:00:00.000Z"
79+
}
80+
],
81+
"sells": 3279,
82+
"buys": 3722,
83+
"graduatedAt": null
84+
}
85+
}
86+
]
87+
```
88+
89+
</details>
90+
91+
#### Get `/api/tokens/{contractAddress}`
92+
93+
Retrieve detailed information for a specific token.
94+
95+
**Parameters:**
96+
97+
<table>
98+
<thead>
99+
<tr>
100+
<th>Parameter</th>
101+
<th>Type</th>
102+
<th>Required</th>
103+
<th>Description</th>
104+
</tr>
105+
</thead>
106+
<tbody>
107+
<tr>
108+
<td>`contractAddress`</td>
109+
<td>string</td>
110+
<td>Yes</td>
111+
<td>Token address</td>
112+
</tr>
113+
</tbody>
114+
</table>
115+
116+
<details>
117+
<summary>**Response**</summary>
118+
119+
```json
120+
{
121+
"name": "Wrapped Ether",
122+
"symbol": "WETH",
123+
"decimals": 18,
124+
"logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/2396.png",
125+
"contractAddress": "0xe5d7c2a44ffddf6b295a15c148167daaaf5cf34f",
126+
"currentPrice": "3321.74000000000000",
127+
"priceUpdatedAt": "2025-01-09T09:36:02.194Z",
128+
"info": {
129+
"prices": [
130+
{
131+
"price": "3321.74000000000000",
132+
"date": "2025-01-09T09:00:00.000Z"
133+
}
134+
],
135+
"sells": 3279,
136+
"buys": 3722,
137+
"graduatedAt": null
138+
}
139+
}
140+
```
141+
142+
</details>
143+
144+
#### Get `/api/tokens/bonded`
145+
146+
Retrieve recently bonded tokens.
147+
148+
<details>
149+
<summary>**Response**</summary>
150+
151+
```json
152+
[
153+
{
154+
"name": "CatWifCap",
155+
"symbol": "CWC",
156+
"decimals": 18,
157+
"logo": "https://d12kvghf2eznx1.cloudfront.net/tokens/images/d0a931cd-7982-47e4-86c7-74be11ab0b09",
158+
"contractAddress": "0x092b9e25a7d143c83d44c27194f5cee7c1150f22",
159+
"currentPrice": "0.00013412000000",
160+
"priceUpdatedAt": "2025-01-09T09:45:04.799Z",
161+
"info": {
162+
"prices": [
163+
{
164+
"price": "0.00013412000000",
165+
"date": "2025-01-09T09:00:00.000Z"
166+
}
167+
],
168+
"sells": 0,
169+
"buys": 0,
170+
"graduatedAt": "2024-12-01T18:19:42.095Z"
171+
}
172+
}
173+
]
174+
```
175+
176+
</details>
177+
178+
#### Get `/api/tokens/most-swapped`
179+
180+
Retrieve the most swapped tokens over the last 24 hours (from the [corresponding Dune query](https://dune.com/queries/4396527)).
181+
182+
<details>
183+
<summary>**Response**</summary>
184+
185+
```json
186+
[
187+
{
188+
"name": "Foxy",
189+
"symbol": "FOXY",
190+
"decimals": 18,
191+
"logo": "https://i.ibb.co/MSKkFbf/logo.png",
192+
"contractAddress": "0x5fbdf89403270a1846f5ae7d113a989f850d1566",
193+
"currentPrice": "0.01080016000000",
194+
"priceUpdatedAt": "2025-01-09T09:50:05.106Z",
195+
"info": {
196+
"prices": [
197+
{
198+
"price": "0.01078276000000",
199+
"date": "2025-01-09T09:00:00.000Z"
200+
}
201+
],
202+
"sells": 219,
203+
"buys": 212,
204+
"graduatedAt": null
205+
}
206+
}
207+
]
208+
```
209+
210+
</details>
211+
212+
#### Get `/api/tokens/top-winners`
213+
214+
Retrieve tokens with the highest price increase over the last 24 hours.
215+
216+
<details>
217+
<summary>**Response**</summary>
218+
219+
```json
220+
[
221+
{
222+
"name": "Yellow Duckies",
223+
"symbol": "DUCKIES",
224+
"decimals": 8,
225+
"logo": "https://assets.coingecko.com/coins/images/27630/thumb/duckies_logo.png?1706528164",
226+
"contractAddress": "0x796000fad0d00b003b9dd8e531ba90cff39e01e0",
227+
"currentPrice": "0.00662527000000",
228+
"priceUpdatedAt": "2025-01-10T14:05:02.603Z",
229+
"last24hVariation": 48.75177091589188,
230+
"info": {
231+
"prices": [],
232+
"sells": 0,
233+
"buys": 0,
234+
"graduatedAt": null
235+
}
236+
}
237+
]
238+
```
239+
240+
</details>
241+
242+
#### Get `/api/tokens/top-losers`
243+
244+
Retrieve tokens with the highest price decrease over the last 24 hours.
245+
246+
<details>
247+
<summary>**Response**</summary>
248+
249+
```json
250+
[
251+
{
252+
"name": "CROAK",
253+
"symbol": "CROAK",
254+
"decimals": 18,
255+
"logo": "https://bafybeiempzjdoflyvrhs6uk3424pij753jus3hz5ztkcri4d3zkyjmyd34.ipfs.dweb.link/logo/coin.png",
256+
"contractAddress": "0xacb54d07ca167934f57f829bee2cc665e1a5ebef",
257+
"currentPrice": "0.00146891000000",
258+
"priceUpdatedAt": "2025-01-10T14:05:03.982Z",
259+
"last24hVariation": -8.218352482560526,
260+
"info": {
261+
"prices": [],
262+
"sells": 30,
263+
"buys": 34,
264+
"graduatedAt": null
265+
}
266+
}
267+
]
268+
```
269+
270+
</details>
271+
272+
## Usage examples
273+
274+
### Simple token price bot
275+
276+
```typescript
277+
async function monitorPriceChange(contractAddress: string, threshold: number) {
278+
const BASE_URL = 'https://not.live.yet';
279+
const initialPrice = await fetch(`${BASE_URL}/api/tokens/${contractAddress}`).then(r => r.json());
280+
281+
setInterval(async () => {
282+
const currentPrice = await fetch(`${BASE_URL}/api/tokens/${contractAddress}`).then(r => r.json());
283+
const priceChange = (currentPrice.price.usd - initialPrice.price.usd) / initialPrice.price.usd;
284+
285+
if (Math.abs(priceChange) > threshold) {
286+
// Execute trading strategy
287+
console.log(`Price changed by ${priceChange}% - Trading signal`);
288+
}
289+
}, 60000); // Check every minute
290+
}
291+
```
292+
293+
## Best practices
294+
295+
1. **Rate limiting**
296+
- This is an alpha version with strict rate limits per calling IP:
297+
- 2 requests per second
298+
- 60 requests per minute
299+
- Cache static data
300+
- Implement backoff strategies when limits are reached
301+
302+
2. **Error handling**
303+
- Always check HTTP status of responses
304+
- Implement retry with exponential backoff
305+
- Validate token addresses before requests
306+
307+
3. **Performance**
308+
- (Not available yet) Use pagination for large lists
309+
- Implement local caching when appropriate
310+
311+
## Security considerations
312+
313+
- Validate all input parameters
314+
- Sanitize response data
315+
316+
## Support and feedback
317+
318+
For technical support or feature requests,
319+
reach out to us on [Discord](https://discord.com/invite/linea) in the [#developer-chat](https://discord.com/channels/1141419161893998702/1141419163223593024) channel.

‎docs/get-started/build/ethereum-differences.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,4 +102,4 @@ The point evaluation precompile was introduced in [EIP-4844](https://eips.ethere
102102
## JSON RPC API
103103

104104
Linea uses the standard Ethereum JSON RPC API methods. However, in a few cases, methods differ from
105-
those on Ethereum. These methods are documented in the [reference section](../../api/index.mdx).
105+
those on Ethereum. These methods are documented in the [reference section](../../api/reference/index.mdx).

‎docs/get-started/how-to/connect-wallet.mdx

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
---
22
title: Connect a wallet to your dapp
3-
description: Learn how to connect a wallet to your dapp so users can interact with your contracts
3+
description: >-
4+
Learn how to connect a wallet to your dapp so users can interact with your
5+
contracts
6+
image: /img/socialCards/connect-a-wallet-to-your-dapp.jpg
47
---
58

69
Enabling users' wallets to connect to your dapp is critical, since it's the only way they can

‎docs/get-started/how-to/run-a-node/index.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This section guides you through running a Linea node using various compatible Et
1111

1212
:::info important
1313
While Linea supports multiple clients, only Linea Besu currently allows you to access Linea-specific
14-
features, such as using [Linea methods](../../../api/index.mdx) (for example, `linea_estimateGas`)
14+
features, such as using [Linea methods](../../../api/reference/index.mdx) (for example, `linea_estimateGas`)
1515
or calling methods using the `finalized` tag.
1616

1717
Linea Besu is recommended for infrastructure providers and operators who intend to run a Linea
@@ -41,7 +41,7 @@ to Linea-specific features.
4141
</tr>
4242
<tr>
4343
<td>[Linea Besu](./linea-besu.mdx)</td>
44-
<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>
44+
<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>
4545
<td>✅</td>
4646
</tr>
4747
<tr>

0 commit comments

Comments
 (0)